diff options
Diffstat (limited to 'doc/builders/packages/nginx.xml')
-rw-r--r-- | doc/builders/packages/nginx.xml | 25 |
1 files changed, 25 insertions, 0 deletions
diff --git a/doc/builders/packages/nginx.xml b/doc/builders/packages/nginx.xml new file mode 100644 index 000000000000..65854ba02366 --- /dev/null +++ b/doc/builders/packages/nginx.xml @@ -0,0 +1,25 @@ +<section xmlns="http://docbook.org/ns/docbook" + xmlns:xlink="http://www.w3.org/1999/xlink" + xml:id="sec-nginx"> + <title>Nginx</title> + + <para> + <link xlink:href="https://nginx.org/">Nginx</link> is a reverse proxy and lightweight webserver. + </para> + + <section xml:id="sec-nginx-etag"> + <title>ETags on static files served from the Nix store</title> + + <para> + HTTP has a couple different mechanisms for caching to prevent clients from having to download the same content repeatedly if a resource has not changed since the last time it was requested. When nginx is used as a server for static files, it implements the caching mechanism based on the <link xlink:href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Last-Modified"><literal>Last-Modified</literal></link> response header automatically; unfortunately, it works by using filesystem timestamps to determine the value of the <literal>Last-Modified</literal> header. This doesn't give the desired behavior when the file is in the Nix store, because all file timestamps are set to 0 (for reasons related to build reproducibility). + </para> + + <para> + Fortunately, HTTP supports an alternative (and more effective) caching mechanism: the <link xlink:href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/ETag"><literal>ETag</literal></link> response header. The value of the <literal>ETag</literal> header specifies some identifier for the particular content that the server is sending (e.g. a hash). When a client makes a second request for the same resource, it sends that value back in an <literal>If-None-Match</literal> header. If the ETag value is unchanged, then the server does not need to resend the content. + </para> + + <para> + As of NixOS 19.09, the nginx package in Nixpkgs is patched such that when nginx serves a file out of <filename>/nix/store</filename>, the hash in the store path is used as the <literal>ETag</literal> header in the HTTP response, thus providing proper caching functionality. This happens automatically; you do not need to do modify any configuration to get this behavior. + </para> + </section> +</section> |