.. highlight:: nginx

.. _ngx-location:

*Location*
==========
Ya se ha discutido que a grandes rasgos una |URL| está compuesta por
:kbd:`esquema://maquina/ruta` u cómo :program:`nginx` selecciona el dominio
virtual adecuado dependiendo de la máquina\ [#]_.  Sin embargo, ya elegido este,
:program:`nginx` permite también alterar el comportamiento dependiendo de cuál
sea la ruta. Para ello existe la directiva location_.  Por
ejemplo::

   server {
      listen 80;
      server_name  _;

      root /srv/www;

      location /favicon.ico {
         log_not_found off;
         access_log off;
         return 410;
      }
   }

En este caso, cuando un navegador pide el recurso :file:`/favicon.ico`, se
aplica una directiva que evita que se registre en los *logs* la petición del
recurso\ [#]_ y, además, se devuelva un código **410** para que el navegador no
vuelva a pedirlo más\ [#]_. Por supuesto, si se pide cualquier otro recurso, la
petición sí se registrará y no se devolverá un error.

.. warning:: No entienda location_ como una :ref:`sentencia condicional
   <ngx-if>` que sirve para aplicar unas directivas particulares a la |URL| que
   cumpla su patrón, de manera que si varias localizaciones son
   adecuadas, se aplicarán las directivas particulares de todas esas
   localizaciones. Los bloques location_ son bloques terminales: cada petición
   acaba por aplicar la configuración de un único bloque location_ (más,
   obviamente, la configuración común del bloque :ref:`server <ngx-server>`): y
   en caso de que varios bloques concuerden con la |URL| se escogerá uno según
   las :ref:`reglas de precedencia <ngx-location-prec>` que se verán más
   adelante. La única forma de que una petición salga de su bloque location_ y
   acabe aplicando otra configuración es quie se encuentre dentro con un
   :ref:`redirección <ngx-rewrite>` exitosa.

.. note:: Pueden anidarse localizaciones, excepto las localicaciones nominales
   (las que usan :kbd:`@`) que no pueden anidar ni ser anidadas.

Expresión de las rutas
----------------------
La directiva location_ permite expresar el patrón a comparar con la ruta de
diversos modos:

* Sin modificador, implica que el patrón debe concordar con el principio de la
  ruta::

      location /docs/ {
         autoindex on;
      }

  de esta manera, direcciones como *http://www.example.net/docs/uno.html* o
  *http://www.example.net/docs/subdir/dos.html* concuerdan con el patrón.

* Con el modificador :kbd:`=`, el patrón debe concordar exactamente con la
  ruta::

      location = /errors/404.html {
         internal;
      }

* Con el modificador :kbd:`~`, el patrón es una expresión regular::

      location ~ \.(jpg|jpeg|png)$ {
         expires max;
      }

  En este caso, la directiva ``expires`` se aplica a las imágenes.

  .. note:: La expresión regular también puede escribirse entre comillas::

         location ~ "\.(jpg|jpeg|png)$" {
            expires max;
         }

    lo cual cobra especial importancia cuando contiene algún carácter que puede
    malinterpretar :program:`nginx` como la llave de apertura ("*{*").

* Con el modificador :kbd:`~*`, el patrón es una expresión regular en que no
  atienden mayúsculas o minusculas::

      location ~* \.(jpe?g|png)$ {
         expires max;
      }

  En este caso una imagen de nombre :file:`foto.JPG` también concordaría.

* Con el modificador :kbd:`^~`, el patrón no es una expresión regular, sino que
  debe concordar con el principio de la ruta exactamente igual que cuando no
  hay modificador. La diferencia la veremos al tratar el orden de precedencia.

* Con el modificador :kbd:`@`, el patrón no es un patrón para rutas, sino un
  nombre que puede usarse en redirecciones. Por ejemplo::

   try_files $uri $uri/ @nombre;

   location @nombre {
      rewrite ^(.*\.(?:jpe?g|png))$ /images$1 last;
   }

.. note:: Como en el caso de ``server_name`` es posible capturar grupos para
   usarlos luego en directivas incluidas dentro del bloque. Véase un ejemplo más
   abajo al :ref:`habilitar los perfiles de usuario <nginx-perfiles>`.

.. _ngx-location-prec:

Precedencia
-----------

Es muy habitual que dentro de un mismo bloque virtual, haya varias
localizaciones. Una petición sólo puede aplicar las directivas incluidas dentro
de una localización (o de ninguna), por lo que hay un orden de precedencia para
determinar cuál de los bloques location_ concordante es aplicable. La
precedencia es la siguiente:

#. La localización con modificador :kbd:`=`.
#. La localización más larga con modificador :kbd:`^~`.
#. La primera localización con expresión regular (indistintamente :kbd:`~` y
   :kbd:`~*`).
#. La localización más larga sin modificador.

.. seealso:: La página `nginx.viraptor.info <https://nginx.viraptor.info/>`_
   calcula, dada una configuración, cuál es el bloque ``server`` y, dentro de él,
   el bloque location_ aplicable para una |URL| determinada.

Alias
-----
Ya introdujimos la directiva :ref:`root <nginx-root>`, que permite indicar cuál
es el directorio en el sistema de ficheros del servidor bajo el cual se sitúan
los ficheros accesibles. Por tanto, si su valor es :file:`/srv/www` y la ruta
del recurso requirida es :file:`/themes/classic/main.css`, el recurso se
encuentra en el servidor en la ruta :file:`/srv/www/themes/classic/main.css`,
esto es, la concatenación del directorio raíz y la ruta expresada en la |URL|.

.. _nginx-alias:

Pero hay otra forma de indicar cuál la ruta en el servidor del recurso y que
requiere el uso location_: `alias
<http://nginx.org/en/docs/http/ngx_http_core_module.html#alias>`_. Con ella, la
ruta absoluta del recurso en el servidor es la concatenación su valor y la ruta
de la |URL| descontada la coincidencia con el patrón de location_. Por
ejemplo::

   location /images/ {
      alias /usr/share/nginx/media/;
   }

En este caso, si se pidiera el recurso *http://www.example.net/images/foto.jpg*,
su ruta en el servidor sería :file:`/usr/share/nginx/media/foto.jpg` y no
:file:`/usr/share/nginx/media/images/foto.jpg`, como habría ocurrido si se
hubiera usado ``root``.

.. _nginx-perfiles:


Sitios personales
-----------------
Es una práctica común, cuando en un servidor se desea que sus usuarios tengan
sitio personal en el que puedan colgar contenidos, que se acceda a ellos a
través de la dirección:

.. code-block:: none

   http://www.example.net/~USUARIO/ruta/hacia/el/recurso

donde *USUARIO* es el nombre de usuario; y que los contenidos se sitúen en el
servidor bajo :file:`~/public_html`. Para lograr esto, en :program:`nginx` basta
con incluir en el dominio virtual (o sea, el bloque ``server``) adecuado, lo
siguiente::

   # Sitios personales (contenido estático)
   location ~ ^/~([^/]+)(.*)$ {
      alias /home/$1/public_html$2;
      autoindex on;
   }      

que logra lo que pretendemos.

.. note:: Este trozo de configuración es muy apropiado para incluirlo como
   contenido de un fichero llamado :file:`snippets/personal.conf` e incluirlo
   después dentro del bloque ``server`` adecuado mediante la directiva
   ``include``:

   .. code-block:: nginx

      include snippets/personal.conf;

.. rubric:: Notas al pie

.. [#] Aunque, en realidad, la máquina se toma del valor del campo ``Host``, no
   de la |URL|, en la práctica los navegadores copian como valor del campo la
   máquina que introduzcamos en la barra de direcciones.

.. [#] Ese recurso es el icono que usa el navegador para adornar el título de la
   ventana y la pestaña. Todos los navegadores nos lo pedirán y, si nosotros no
   lo hemos definido, se generará un enfadoso error en el registro. Para
   evitarlo, nada mejor que las líneas sugeridas. Con la directiva
   :kbd:`access_log off` no se registrá nunca la petición, incluso si sí hemos
   creado un *favicon* para nuestro sitio.

.. [#] Con todo parece que --al menos-- *Chrome* no presta mucho caso a ello y
   sigue pidiendo el *favicon*.

.. |URL| replace:: :abbr:`URL (Uniform Resource Locator)`
.. _location: http://nginx.org/en/docs/http/ngx_http_core_module.html#location
.. _server: http://nginx.org/en/docs/http/ngx_http_core_module.html#server