Merge pull request #2197 from jivanpal/patch-2

Update nginx.rst -- Reworked the Nginx configs
2026-01-02 17:59:36 +07:00 · 2020-08-10 16:52:48 +02:00
parent 9a253e84f1 2fa446d4e2
commit c88a15c11b
1 changed files with 191 additions and 198 deletions
--- a/admin_manual/installation/nginx.rst
+++ b/admin_manual/installation/nginx.rst
@@ -11,13 +11,6 @@ server. These configurations examples were originally provided by
   **ssl_certificate_key** to suit your needs.
 -  Make sure your SSL certificates are readable by the server (see `nginx HTTP
   SSL Module documentation <http://wiki.nginx.org/HttpSslModule>`_).
-  ``add_header`` statements are only taken from the current level and are not
-   cascaded from or to a different level. All necessary ``add_header``
-   statements must be defined in each level needed. For better readability it
-   is possible to move *common* add header statements into a separate file
-   and include that file wherever necessary. However, each ``add_header``
-   statement must be written in a single line to prevent connection problems
-   with sync clients.
 -  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
@@ -41,67 +34,29 @@ webroot of your nginx installation. In this example it is
      listen 80;
      listen [::]:80;
      server_name cloud.example.com;
-      # enforce https
-      return 301 https://$server_name:443$request_uri;
+      
+      # Enforce HTTPS
+      return 301 https://$server_name$request_uri;
  }

  server {
-      listen 443 ssl http2;
+      listen 443      ssl http2;
      listen [::]:443 ssl http2;
      server_name cloud.example.com;

      # Use Mozilla's guidelines for SSL/TLS settings
      # https://mozilla.github.io/server-side-tls/ssl-config-generator/
-      # NOTE: some settings below might be redundant
-      ssl_certificate /etc/ssl/nginx/cloud.example.com.crt;
+      ssl_certificate     /etc/ssl/nginx/cloud.example.com.crt;
      ssl_certificate_key /etc/ssl/nginx/cloud.example.com.key;

-      # Add headers to serve security related headers
-      # Before enabling Strict-Transport-Security headers please read into this
-      # topic first.
-      #add_header Strict-Transport-Security "max-age=15768000; includeSubDomains; preload;" always;
-      #
+      # HSTS settings
      # WARNING: Only add the preload option once you read about
      # the consequences in https://hstspreload.org/. This option
      # will add the domain to a hardcoded list that is shipped
      # in all major browsers and getting removed from this list
      # could take several months.
-      add_header Referrer-Policy "no-referrer" always;
-      add_header X-Content-Type-Options "nosniff" always;
-      add_header X-Download-Options "noopen" always;
-      add_header X-Frame-Options "SAMEORIGIN" always;
-      add_header X-Permitted-Cross-Domain-Policies "none" always;
-      add_header X-Robots-Tag "none" always;
-      add_header X-XSS-Protection "1; mode=block" always;
-
-      # Remove X-Powered-By, which is an information leak
-      fastcgi_hide_header X-Powered-By;
-
-      # Path to the root of your installation
-      root /var/www/nextcloud;
-
-      location = /robots.txt {
-          allow all;
-          log_not_found off;
-          access_log off;
-      }
-
-      # The following 2 rules are only needed for the user_webfinger app.
-      # Uncomment it if you're planning to use this app.
-      #rewrite ^/.well-known/host-meta /public.php?service=host-meta last;
-      #rewrite ^/.well-known/host-meta.json /public.php?service=host-meta-json last;
-
-      # The following rule is only needed for the Social app.
-      # Uncomment it if you're planning to use this app.
-      #rewrite ^/.well-known/webfinger /public.php?service=webfinger last;
-
-      location = /.well-known/carddav {
-        return 301 $scheme://$host:$server_port/remote.php/dav;
-      }
-      location = /.well-known/caldav {
-        return 301 $scheme://$host:$server_port/remote.php/dav;
-      }
-
+      #add_header Strict-Transport-Security "max-age=15768000; includeSubDomains; preload;" always;
+      
      # set max upload size
      client_max_body_size 512M;
      fastcgi_buffers 64 4K;
@@ -114,75 +69,112 @@ webroot of your nginx installation. In this example it is
      gzip_proxied expired no-cache no-store private no_last_modified no_etag auth;
      gzip_types application/atom+xml application/javascript application/json application/ld+json application/manifest+json application/rss+xml application/vnd.geo+json application/vnd.ms-fontobject application/x-font-ttf application/x-web-app-manifest+json application/xhtml+xml application/xml font/opentype image/bmp image/svg+xml image/x-icon text/cache-manifest text/css text/plain text/vcard text/vnd.rim.location.xloc text/vtt text/x-component text/x-cross-domain-policy;

-      # Uncomment if your server is build with the ngx_pagespeed module
-      # This module is currently not supported.
+      # Pagespeed is not supported by Nextcloud, so if your server is built
+      # with the `ngx_pagespeed` module, uncomment this line to disable it.
      #pagespeed off;
-
-      location / {
-          rewrite ^ /index.php;
+      
+      # HTTP response headers borrowed from Nextcloud `.htaccess`
+      add_header Referrer-Policy                      "no-referrer"   always;
+      add_header X-Content-Type-Options               "nosniff"       always;
+      add_header X-Download-Options                   "noopen"        always;
+      add_header X-Frame-Options                      "SAMEORIGIN"    always;
+      add_header X-Permitted-Cross-Domain-Policies    "none"          always;
+      add_header X-Robots-Tag                         "none"          always;
+      add_header X-XSS-Protection                     "1; mode=block" always;
+      
+      # Remove X-Powered-By, which is an information leak
+      fastcgi_hide_header X-Powered-By;
+      
+      # Path to the root of your installation
+      root /var/www/nextcloud;
+      
+      # Specify how to handle directories -- specifying `/index.php$request_uri`
+      # here as the fallback means that Nginx always exhibits the desired behaviour
+      # when a client requests a path that corresponds to a directory that exists
+      # on the server. In particular, if that directory contains an index.php file,
+      # that file is correctly served; if it doesn't, then the request is passed to
+      # the front-end controller. This consistent behaviour means that we don't need
+      # to specify custom rules for certain paths (e.g. images and other assets,
+      # `/updater`, `/ocm-provider`, `/ocs-provider`), and thus
+      # `try_files $uri $uri/ /index.php$request_uri`
+      # always provides the desired behaviour.
+      index index.php index.html /index.php$request_uri;
+      
+      # Default Cache-Control policy
+      expires 1m;
+      
+      # Rule borrowed from `.htaccess` to handle Microsoft DAV clients
+      location = / {
+          if ( $http_user_agent ~ ^DavClnt ) {
+              return 302 /remote.php/webdav/$is_args$args;
+          }
      }
-
-      location ~ ^\/(?:build|tests|config|lib|3rdparty|templates|data)\/ {
-          deny all;
-      }
-      location ~ ^\/(?:\.|autotest|occ|issue|indie|db_|console) {
-          deny all;
+      
+      location = /robots.txt {
+          allow all;
+          log_not_found off;
+          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 {
+          # The following 6 rules are borrowed from `.htaccess`
+      
+          rewrite ^/\.well-known/host-meta\.json  /public.php?service=host-meta-json  last;
+          rewrite ^/\.well-known/host-meta        /public.php?service=host-meta       last;
+          rewrite ^/\.well-known/webfinger        /public.php?service=webfinger       last;
+          rewrite ^/\.well-known/nodeinfo         /public.php?service=nodeinfo        last;
+          
+          location = /.well-known/carddav     { return 301 /remote.php/dav/; }
+          location = /.well-known/caldav      { return 301 /remote.php/dav/; }

-      location ~ ^\/(?:index|remote|public|cron|core\/ajax\/update|status|ocs\/v[12]|updater\/.+|oc[ms]-provider\/.+|.+\/richdocumentscode\/proxy)\.php(?:$|\/) {
-          fastcgi_split_path_info ^(.+?\.php)(\/.*|)$;
+          try_files $uri $uri/ =404;
+      }
+      
+      # Rules borrowed from `.htaccess` to hide certain paths from clients
+      location ~ ^/(?:build|tests|config|lib|3rdparty|templates|data)(?:$|/)  { return 404; }
+      location ~ ^/(?:\.|autotest|occ|issue|indie|db_|console)              { return 404; }
+      
+      # Ensure this block, which passes PHP files to the PHP process, is above the blocks
+      # which handle static assets (as seen below). If this block is not declared first,
+      # then Nginx will encounter an infinite rewriting loop when it prepends `/index.php`
+      # to the URI, resulting in a HTTP 500 error response.
+      location ~ \.php(?:$|/) {
+          fastcgi_split_path_info ^(.+?\.php)(/.*)$;
          set $path_info $fastcgi_path_info;
+          
          try_files $fastcgi_script_name =404;
+          
          include fastcgi_params;
          fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
          fastcgi_param PATH_INFO $path_info;
          fastcgi_param HTTPS on;
-          # Avoid sending the security headers twice
-          fastcgi_param modHeadersAvailable true;
-          # Enable pretty urls
-          fastcgi_param front_controller_active true;
+          
+          fastcgi_param modHeadersAvailable true;         # Avoid sending the security headers twice
+          fastcgi_param front_controller_active true;     # Enable pretty urls
          fastcgi_pass php-handler;
+          
          fastcgi_intercept_errors on;
          fastcgi_request_buffering off;
      }
-
-      location ~ ^\/(?:updater|oc[ms]-provider)(?:$|\/) {
-          try_files $uri/ =404;
-          index index.php;
-      }
-
-      # Adding the cache control header for js, css and map files
-      # Make sure it is BELOW the PHP block
-      location ~ \.(?:css|js|woff2?|svg|gif|map)$ {
+      
+      location ~ \.(?:css|js|svg|gif)$ {
          try_files $uri /index.php$request_uri;
-          add_header Cache-Control "public, max-age=15778463";
-          # Add headers to serve security related headers (It is intended to
-          # have those duplicated to the ones above)
-          # Before enabling Strict-Transport-Security headers please read into
-          # this topic first.
-          #add_header Strict-Transport-Security "max-age=15768000; includeSubDomains; preload;" always;
-          #
-          # WARNING: Only add the preload option once you read about
-          # the consequences in https://hstspreload.org/. This option
-          # will add the domain to a hardcoded list that is shipped
-          # in all major browsers and getting removed from this list
-          # could take several months.
-          add_header Referrer-Policy "no-referrer" always;
-          add_header X-Content-Type-Options "nosniff" always;
-          add_header X-Download-Options "noopen" always;
-          add_header X-Frame-Options "SAMEORIGIN" always;
-          add_header X-Permitted-Cross-Domain-Policies "none" always;
-          add_header X-Robots-Tag "none" always;
-          add_header X-XSS-Protection "1; mode=block" always;
-
-          # Optional: Don't log access to assets
-          access_log off;
+          expires 6M;         # Cache-Control policy borrowed from `.htaccess`
+          access_log off;     # Optional: Don't log access to assets
      }
-
-      location ~ \.(?:png|html|ttf|ico|jpg|jpeg|bcmap|mp4|webm|mp3|ogg|wav)$ {
+      
+      location ~ \.woff2?$ {
          try_files $uri /index.php$request_uri;
-          # Optional: Don't log access to other assets
-          access_log off;
+          expires 7d;         # Cache-Control policy borrowed from `.htaccess`
+          access_log off;     # Optional: Don't log access to assets
+      }
+      
+      location / {
+          try_files $uri $uri/ /index.php$request_uri;
      }
  }

@@ -191,8 +183,15 @@ Nextcloud in a subdir of the nginx webroot

 The following config should be used when Nextcloud is placed within a subdir of
 the webroot of your nginx installation.
-In this example the webroot is located at
-``/var/www`` and the Nextcloud instance is accessed via ``http(s)://cloud.example.com/nextcloud/``
+In this example the Nextcloud files are located at
+``/var/www/nextcloud`` and the Nextcloud instance is accessed via ``http(s)://cloud.example.com/nextcloud/``.
+The configuration differs from the "Nextcloud in webroot" configuration above in the following ways:
+
+- All requests for ``/nextcloud`` are encapsulated within a single ``location`` block, namely ``location ^~ /nextcloud``.
+- 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.

 .. code-block:: nginx

@@ -205,71 +204,55 @@ In this example the webroot is located at
      listen 80;
      listen [::]:80;
      server_name cloud.example.com;
-      # enforce https
-      return 301 https://$server_name:443$request_uri;
+
+      # Enforce HTTPS just for `/nextcloud`
+      location /nextcloud {
+          return 301 https://$server_name$request_uri;
+      }
  }

  server {
-      listen 443 ssl http2;
+      listen 443      ssl http2;
      listen [::]:443 ssl http2;
      server_name cloud.example.com;

      # Use Mozilla's guidelines for SSL/TLS settings
      # https://mozilla.github.io/server-side-tls/ssl-config-generator/
-      # NOTE: some settings below might be redundant
-      ssl_certificate /etc/ssl/nginx/cloud.example.com.crt;
+      ssl_certificate     /etc/ssl/nginx/cloud.example.com.crt;
      ssl_certificate_key /etc/ssl/nginx/cloud.example.com.key;

-      # Add headers to serve security related headers
-      # Before enabling Strict-Transport-Security headers please read into this
-      # topic first.
-      #add_header Strict-Transport-Security "max-age=15768000; includeSubDomains; preload;" always;
-      #
+      # HSTS settings
      # WARNING: Only add the preload option once you read about
      # the consequences in https://hstspreload.org/. This option
      # will add the domain to a hardcoded list that is shipped
      # in all major browsers and getting removed from this list
      # could take several months.
-      add_header Referrer-Policy "no-referrer" always;
-      add_header X-Content-Type-Options "nosniff" always;
-      add_header X-Download-Options "noopen" always;
-      add_header X-Frame-Options "SAMEORIGIN" always;
-      add_header X-Permitted-Cross-Domain-Policies "none" always;
-      add_header X-Robots-Tag "none" always;
-      add_header X-XSS-Protection "1; mode=block" always;
+      #add_header Strict-Transport-Security "max-age=15768000; includeSubDomains; preload;" always;

-      # Remove X-Powered-By, which is an information leak
-      fastcgi_hide_header X-Powered-By;
-
-      # Path to the root of your installation
+      # Path to the root of the domain
      root /var/www;
-
+      
      location = /robots.txt {
          allow all;
          log_not_found off;
          access_log off;
      }

-      # The following 2 rules are only needed for the user_webfinger app.
-      # Uncomment it if you're planning to use this app.
-      #rewrite ^/.well-known/host-meta /nextcloud/public.php?service=host-meta last;
-      #rewrite ^/.well-known/host-meta.json /nextcloud/public.php?service=host-meta-json last;
+      location /.well-known {
+          # The following 6 rules are borrowed from `.htaccess`

-      # The following rule is only needed for the Social app.
-      # Uncomment it if you're planning to use this app.
-      #rewrite ^/.well-known/webfinger /nextcloud/public.php?service=webfinger last;
+          rewrite ^/\.well-known/host-meta\.json  /nextcloud/public.php?service=host-meta-json    last;
+          rewrite ^/\.well-known/host-meta        /nextcloud/public.php?service=host-meta         last;
+          rewrite ^/\.well-known/webfinger        /nextcloud/public.php?service=webfinger         last;
+          rewrite ^/\.well-known/nodeinfo         /nextcloud/public.php?service=nodeinfo          last;

-      location = /.well-known/carddav {
-        return 301 $scheme://$host:$server_port/nextcloud/remote.php/dav;
+          location = /.well-known/carddav   { return 301 /nextcloud/remote.php/dav/; }
+          location = /.well-known/caldav    { return 301 /nextcloud/remote.php/dav/; }
+
+          try_files $uri $uri/ =404;
      }
-      location = /.well-known/caldav {
-        return 301 $scheme://$host:$server_port/nextcloud/remote.php/dav;
-      }
-
-      location /.well-known/acme-challenge { }
-
+      
      location ^~ /nextcloud {
-
          # set max upload size
          client_max_body_size 512M;
          fastcgi_buffers 64 4K;
@@ -282,75 +265,85 @@ In this example the webroot is located at
          gzip_proxied expired no-cache no-store private no_last_modified no_etag auth;
          gzip_types application/atom+xml application/javascript application/json application/ld+json application/manifest+json application/rss+xml application/vnd.geo+json application/vnd.ms-fontobject application/x-font-ttf application/x-web-app-manifest+json application/xhtml+xml application/xml font/opentype image/bmp image/svg+xml image/x-icon text/cache-manifest text/css text/plain text/vcard text/vnd.rim.location.xloc text/vtt text/x-component text/x-cross-domain-policy;

-          # Uncomment if your server is build with the ngx_pagespeed module
-          # This module is currently not supported.
+          # Pagespeed is not supported by Nextcloud, so if your server is built
+          # with the `ngx_pagespeed` module, uncomment this line to disable it.
          #pagespeed off;
+          
+          # HTTP response headers borrowed from Nextcloud `.htaccess`
+          add_header Referrer-Policy                      "no-referrer"   always;
+          add_header X-Content-Type-Options               "nosniff"       always;
+          add_header X-Download-Options                   "noopen"        always;
+          add_header X-Frame-Options                      "SAMEORIGIN"    always;
+          add_header X-Permitted-Cross-Domain-Policies    "none"          always;
+          add_header X-Robots-Tag                         "none"          always;
+          add_header X-XSS-Protection                     "1; mode=block" always;
+          
+          # Remove X-Powered-By, which is an information leak
+          fastcgi_hide_header X-Powered-By;
+          
+          # Specify how to handle directories -- specifying `/nextcloud/index.php$request_uri`
+          # here as the fallback means that Nginx always exhibits the desired behaviour
+          # when a client requests a path that corresponds to a directory that exists
+          # on the server. In particular, if that directory contains an index.php file,
+          # that file is correctly served; if it doesn't, then the request is passed to
+          # the front-end controller. This consistent behaviour means that we don't need
+          # to specify custom rules for certain paths (e.g. images and other assets,
+          # `/updater`, `/ocm-provider`, `/ocs-provider`), and thus
+          # `try_files $uri $uri/ /nextcloud/index.php$request_uri`
+          # always provides the desired behaviour.
+          index index.php index.html /nextcloud/index.php$request_uri;
+          
+          # Default Cache-Control policy
+          expires 1m;

-          location /nextcloud {
-              rewrite ^ /nextcloud/index.php;
+          # Rule borrowed from `.htaccess` to handle Microsoft DAV clients
+          location = /nextcloud {
+              if ( $http_user_agent ~ ^DavClnt ) {
+                  return 302 /nextcloud/remote.php/webdav/$is_args$args;
+              }
          }
-
-          location ~ ^\/nextcloud\/(?:build|tests|config|lib|3rdparty|templates|data)\/ {
-              deny all;
-          }
-          location ~ ^\/nextcloud\/(?:\.|autotest|occ|issue|indie|db_|console) {
-              deny all;
-          }
-
-          location ~ ^\/nextcloud\/(?:index|remote|public|cron|core\/ajax\/update|status|ocs\/v[12]|updater\/.+|oc[ms]-provider\/.+|.+\/richdocumentscode\/proxy)\.php(?:$|\/) {
-              fastcgi_split_path_info ^(.+?\.php)(\/.*|)$;
+          
+          # Rules borrowed from `.htaccess` to hide certain paths from clients
+          location ~ ^/nextcloud/(?:build|tests|config|lib|3rdparty|templates|data)(?:$|/)    { return 404; }
+          location ~ ^/nextcloud/(?:\.|autotest|occ|issue|indie|db_|console)                { return 404; }
+          
+          # Ensure this block, which passes PHP files to the PHP process, is above the blocks
+          # which handle static assets (as seen below). If this block is not declared first,
+          # then Nginx will encounter an infinite rewriting loop when it prepends
+          # `/nextcloud/index.php` to the URI, resulting in a HTTP 500 error response.
+          location ~ \.php(?:$|/) {
+              fastcgi_split_path_info ^(.+?\.php)(/.*)$;
              set $path_info $fastcgi_path_info;
+              
              try_files $fastcgi_script_name =404;
+              
              include fastcgi_params;
              fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
              fastcgi_param PATH_INFO $path_info;
              fastcgi_param HTTPS on;
-              # Avoid sending the security headers twice
-              fastcgi_param modHeadersAvailable true;
-              # Enable pretty urls
-              fastcgi_param front_controller_active true;
+              
+              fastcgi_param modHeadersAvailable true;         # Avoid sending the security headers twice
+              fastcgi_param front_controller_active true;     # Enable pretty urls
              fastcgi_pass php-handler;
+              
              fastcgi_intercept_errors on;
              fastcgi_request_buffering off;
          }
-
-          location ~ ^\/nextcloud\/(?:updater|oc[ms]-provider)(?:$|\/) {
-              try_files $uri/ =404;
-              index index.php;
-          }
-
-          # Adding the cache control header for js, css and map files
-          # Make sure it is BELOW the PHP block
-          location ~ ^\/nextcloud\/.+[^\/]\.(?:css|js|woff2?|svg|gif|map)$ {
+          
+          location ~ \.(?:css|js|svg|gif)$ {
              try_files $uri /nextcloud/index.php$request_uri;
-              add_header Cache-Control "public, max-age=15778463";
-              # Add headers to serve security related headers  (It is intended
-              # to have those duplicated to the ones above)
-              # Before enabling Strict-Transport-Security headers please read
-              # into this topic first.
-              #add_header Strict-Transport-Security "max-age=15768000; includeSubDomains; preload;" always;
-              #
-              # WARNING: Only add the preload option once you read about
-              # the consequences in https://hstspreload.org/. This option
-              # will add the domain to a hardcoded list that is shipped
-              # in all major browsers and getting removed from this list
-              # could take several months.
-              add_header Referrer-Policy "no-referrer" always;
-              add_header X-Content-Type-Options "nosniff" always;
-              add_header X-Download-Options "noopen" always;
-              add_header X-Frame-Options "SAMEORIGIN" always;
-              add_header X-Permitted-Cross-Domain-Policies "none" always;
-              add_header X-Robots-Tag "none" always;
-              add_header X-XSS-Protection "1; mode=block" always;
-
-              # Optional: Don't log access to assets
-              access_log off;
+              expires 6M;         # Cache-Control policy borrowed from `.htaccess`
+              access_log off;     # Optional: Don't log access to assets
          }
-
-          location ~ ^\/nextcloud\/.+[^\/]\.(?:png|html|ttf|ico|jpg|jpeg|bcmap|mp4|webm|mp3|ogg|wav)$ {
+          
+          location ~ \.woff2?$ {
              try_files $uri /nextcloud/index.php$request_uri;
-              # Optional: Don't log access to other assets
-              access_log off;
+              expires 7d;         # Cache-Control policy borrowed from `.htaccess`
+              access_log off;     # Optional: Don't log access to assets
+          }
+          
+          location /nextcloud {
+              try_files $uri $uri/ /nextcloud/index.php$request_uri;
          }
      }
  }