<!--
  Copyright (C) Igor Sysoev
  Copyright (C) Nginx, Inc.
  -->

<!DOCTYPE article SYSTEM "../../../../dtd/article.dtd">

<article name="Server names"
         link="/en/docs/http/server_names.html"
         lang="en"
         rev="5"
         author="Igor Sysoev"
         editor="Brian Mercer">


<section>

<para>
Server names are defined using the
<link doc="ngx_http_core_module.xml" id="server_name"/>
directive
and determine which <link doc="ngx_http_core_module.xml" id="server"/> block
is used for a given request.
See also “<link doc="request_processing.xml"/>”.
They may be defined using exact names, wildcard names, or regular expressions:

<programlisting>
server {
    listen       80;
    server_name  example.org  www.example.org;
    ...
}

server {
    listen       80;
    server_name  *.example.org;
    ...
}

server {
    listen       80;
    server_name  mail.*;
    ...
}

server {
    listen       80;
    server_name  ~^(?&lt;user&gt;.+)\.example\.net$;
    ...
}
</programlisting>
</para>

<para>
When searching for a virtual server by name, if name matches more than one of
the specified variants, e.g. both wildcard name and regular expression match,
the first matching variant will be chosen, in the following order of precedence:
<list type="enum">

<listitem>
exact name
</listitem>

<listitem>
longest wildcard name starting with an asterisk, e.g.
“<literal>*.example.org</literal>”
</listitem>

<listitem>
longest wildcard name ending with an asterisk, e.g. “<literal>mail.*</literal>”
</listitem>

<listitem>
first matching regular expression
(in order of appearance in a configuration file)
</listitem>

</list>
</para>

</section>


<section id="wildcard_names"
        name="Wildcard names">

<para>
A wildcard name may contain an asterisk only on the name’s start or end,
and only on a dot border. The names “<literal>www.*.example.org</literal>”
and “<literal>w*.example.org</literal>” are invalid.
However, these names can be specified using regular expressions,
for example, “<literal>~^www\..+\.example\.org$</literal>” and
“<literal>~^w.*\.example\.org$</literal>”.
An asterisk can match several name parts.
The name “<literal>*.example.org</literal>” matches not only
<literal>www.example.org</literal> but <literal>www.sub.example.org</literal> as well.
</para>

<para>
A special wildcard name in the form “<literal>.example.org</literal>” can be
used to match both the exact name “<literal>example.org</literal>”
and the wildcard name “<literal>*.example.org</literal>”.
</para>

</section>


<section id="regex_names"
        name="Regular expressions names">

<para>
The regular expressions used by nginx are compatible with those used
by the Perl programming language (PCRE).
To use a regular expression, the server name must start with the tilde
character:

<programlisting>
server_name  ~^www\d+\.example\.net$;
</programlisting>

otherwise it will be treated as an exact name, or if the expression contains
an asterisk, as a wildcard name (and most likely as an invalid one).
Do not forget to set “<literal>^</literal>” and “<literal>$</literal>” anchors.
They are not required syntactically, but logically.
Also note that domain name dots should be escaped with a backslash.
A regular expression containing the characters “<literal>{</literal>”
and “<literal>}</literal>” should be quoted:

<programlisting>
server_name  "~^(?&lt;name&gt;\w\d<b>{</b>1,3<b>}</b>+)\.example\.net$";
</programlisting>

otherwise nginx will fail to start and display the error message:

<programlisting>
directive "server_name" is not terminated by ";" in ...
</programlisting>

A named regular expression capture can be used later as a variable:

<programlisting>
server {
    server_name   ~^(www\.)?(<b>?&lt;domain&gt;</b>.+)$;

    location / {
        root   /sites/<b>$domain</b>;
    }
}
</programlisting>

The PCRE library supports named captures using the following syntax:

<table note="yes">

<tr>
<td><literal>?&lt;<value>name</value>&gt;</literal></td>
<td>Perl 5.10 compatible syntax, supported since PCRE-7.0</td>
</tr>

<tr>
<td><literal>?'<value>name</value>'</literal></td>
<td>Perl 5.10 compatible syntax, supported since PCRE-7.0</td>
</tr>

<tr>
<td><literal>?P&lt;<value>name</value>&gt;</literal></td>
<td>Python compatible syntax, supported since PCRE-4.0</td>
</tr>

</table>

If nginx fails to start and displays the error message:

<programlisting>
pcre_compile() failed: unrecognized character after (?&lt; in ...
</programlisting>

this means that the PCRE library is old and the syntax
“<literal>?P&lt;<value>name</value>&gt;</literal>” should be tried instead.
The captures can also be used in digital form:

<programlisting>
server {
    server_name   ~^(www\.)?(.+)$;

    location / {
        root   /sites/<b>$2</b>;
    }
}
</programlisting>

However, such usage should be limited to simple cases (like the above),
since the digital references can easily be overwritten.
</para>


</section>


<section id="miscellaneous_names"
        name="Miscellaneous names">

<para>
There are some server names that are treated specially.
</para>

<para>
If it is required to process requests without the <header>Host</header>
header field in a <link doc="ngx_http_core_module.xml" id="server"/>
block which is not the default, an empty name should be specified:

<programlisting>
server {
    listen       80;
    server_name  example.org  www.example.org  "";
    ...
}
</programlisting>
</para>

<para>
If no
<link doc="ngx_http_core_module.xml" id="server_name"/>
is defined in a <link doc="ngx_http_core_module.xml" id="server"/> block
then nginx uses the empty name as the server name.
<note>
nginx versions up to 0.8.48 used the machine’s hostname as the server name
in this case.
</note>
</para>

<para>
If a server name is defined as “<literal>$hostname</literal>” (0.9.4), the
machine’s hostname is used.
</para>

<para>
If someone makes a request using an IP address instead of a server name,
the <header>Host</header> request header field will contain the IP address
and the request can be handled using the IP address as the server name:

<programlisting>
server {
    listen       80;
    server_name  example.org
                 www.example.org
                 ""
                 <b>192.168.1.1</b>
                 ;
    ...
}
</programlisting>
</para>

<para>
In catch-all server examples the strange name “<literal>_</literal>” can
be seen:

<programlisting>
server {
    listen       80  default_server;
    server_name  _;
    return       444;
}
</programlisting>

There is nothing special about this name, it is just one of a myriad
of invalid domain names which never intersect with any real name.
Other invalid names like “<literal>--</literal>” and “<literal>!@#</literal>”
may equally be used.
</para>

<para>
nginx versions up to 0.6.25 supported the special name “<literal>*</literal>”
which was erroneously interpreted to be a catch-all name.
It never functioned as a catch-all or wildcard server name.
Instead, it supplied the functionality that is now provided
by the
<link doc="ngx_http_core_module.xml" id="server_name_in_redirect"/>
directive.
The special name “<literal>*</literal>” is now deprecated
and the
<link doc="ngx_http_core_module.xml" id="server_name_in_redirect"/>
directive should be used.
Note that there is no way to specify the catch-all name or
the default server using the
<link doc="ngx_http_core_module.xml" id="server_name"/>
directive.
This is a property of the
<link doc="ngx_http_core_module.xml" id="listen"/>
directive
and not of the
<link doc="ngx_http_core_module.xml" id="server_name"/>
directive.
See also “<link doc="request_processing.xml"/>”.
It is possible to define servers listening on ports *:80 and *:8080,
and direct that one will be the default server for port *:8080,
while the other will be the default for port *:80:

<programlisting>
server {
    listen       80;
    listen       8080  default_server;
    server_name  example.net;
    ...
}

server {
    listen       80  default_server;
    listen       8080;
    server_name  example.org;
    ...
}
</programlisting>
</para>


</section>


<section id="idn"
        name="Internationalized names">
<para>
Internationalized domain names
(<link url="https://en.wikipedia.org/wiki/Internationalized_domain_name">IDNs</link>)
should be specified using an ASCII (Punycode) representation
in the <link doc="ngx_http_core_module.xml" id="server_name"/> directive:
<programlisting>
server {
    listen       80;
    server_name  xn--e1afmkfd.xn--80akhbyknj4f;  # пример.испытание
    ...
}
</programlisting>
</para>

</section>


<section id="virtual_server_selection"
        name="Virtual server selection">

<para>
First, a connection is created in a default server context.
Then, the server name can be determined
in the following request processing stages,
each involved in server configuration selection:

<list type="bullet">

<listitem>
<para>
during SSL handshake, in advance, according to
<link doc="configuring_https_servers.xml" id="sni">SNI</link>
</para>
</listitem>

<listitem>
<para>
after processing the request line
</para>
</listitem>

<listitem>
<para>
after processing the <literal>Host</literal> header field
</para>
</listitem>

<listitem>
<para>
if the server name was not determined after processing the request line or
from the <literal>Host</literal> header field,
nginx will use the empty name as the server name.
</para>
</listitem>

</list>

At each of these stages, different server configurations can be applied.
As such, certain directives should be specified with caution:
<list type="bullet">

<listitem>
in case of the
<link doc="ngx_http_ssl_module.xml" id="ssl_protocols"/> directive,
the protocol list is set by the OpenSSL library before
the server configuration could be applied according to the name
requested through SNI,
thus, protocols should be specified only for a default server;
</listitem>

<listitem>
the
<link doc="ngx_http_core_module.xml" id="client_header_buffer_size"/>
and
<link doc="ngx_http_core_module.xml" id="merge_slashes"/> directives
are involved before reading the request line,
thus, such directives use a default server configuration or
the server configuration chosen by SNI;
</listitem>

<listitem>
in case of the
<link doc="ngx_http_core_module.xml" id="ignore_invalid_headers"/>,
<link doc="ngx_http_core_module.xml" id="large_client_header_buffers"/>,
<link doc="ngx_http_core_module.xml" id="max_headers"/>,
and
<link doc="ngx_http_core_module.xml" id="underscores_in_headers"/> directives
involved in processing request header fields,
it additionally depends
whether the server configuration was updated
according to the request line or the <literal>Host</literal> header field;
</listitem>

<listitem>
an error response will be handled with
the <link doc="ngx_http_core_module.xml" id="error_page"/> directive
in the server that currently fulfills the request.
</listitem>

</list>
</para>

</section>


<section id="optimization"
        name="Optimization">

<para>
Exact names, wildcard names starting with an asterisk,
and wildcard names ending with an asterisk are stored
in three hash tables bound to the listen ports.
The sizes of hash tables are optimized at the configuration phase
so that a name can be found with the fewest CPU cache misses.
The details of setting up hash tables are provided in a separate
<link doc="../hash.xml">document</link>.
</para>

<para>
The exact names hash table is searched first.
If a name is not found, the hash table with wildcard names
starting with an asterisk is searched.
If the name is not found there, the hash table with wildcard names
ending with an asterisk is searched.
</para>

<para>
Searching wildcard names hash table is slower than searching exact names hash
table because names are searched by domain parts.
Note that the special wildcard form “<literal>.example.org</literal>”
is stored in a wildcard names hash table and not in an exact names hash table.
</para>

<para>
Regular expressions are tested sequentially
and therefore are the slowest method and are non-scalable.
</para>

<para>
For these reasons, it is better to use exact names where possible.
For example, if the most frequently requested names of a server
are <literal>example.org</literal> and <literal>www.example.org</literal>,
it is more efficient to define them explicitly:

<programlisting>
server {
    listen       80;
    server_name  example.org  www.example.org  *.example.org;
    ...
}
</programlisting>

than to use the simplified form:

<programlisting>
server {
    listen       80;
    server_name  .example.org;
    ...
}
</programlisting>
</para>

<para>
If a large number of server names are defined,
or unusually long server names are defined, tuning
the <link doc="ngx_http_core_module.xml" id="server_names_hash_max_size"/>
and <link doc="ngx_http_core_module.xml" id="server_names_hash_bucket_size"/>
directives at the <i>http</i> level may become necessary.
The default value of the
<link doc="ngx_http_core_module.xml" id="server_names_hash_bucket_size"/>
directive may be equal to 32, or 64, or another value,
depending on CPU cache line size.
If the default value is 32 and server name is defined as
“<literal>too.long.server.name.example.org</literal>”
then nginx will fail to start and display the error message:

<programlisting>
could not build the server_names_hash,
you should increase server_names_hash_bucket_size: 32
</programlisting>

In this case, the directive value should be increased to the next power of two:

<programlisting>
http {
    server_names_hash_bucket_size  64;
    ...
</programlisting>

If a large number of server names are defined,
another error message will appear:

<programlisting>
could not build the server_names_hash,
you should increase either server_names_hash_max_size: 512
or server_names_hash_bucket_size: 32
</programlisting>

In such a case, first try to set
<link doc="ngx_http_core_module.xml" id="server_names_hash_max_size"/>
to a number close to the number of server names.
Only if this does not help,
or if nginx’s start time is unacceptably long, try to increase
<link doc="ngx_http_core_module.xml" id="server_names_hash_bucket_size"/>.
</para>

<para>
If a server is the only server for a listen port, then nginx will not test
server names at all (and will not build the hash tables for the listen port).
However, there is one exception.
If a server name is a regular expression with captures,
then nginx has to execute the expression to get the captures.
</para>

</section>


<section id="compatibility"
        name="Compatibility">

<para>
<list type="bullet">

<listitem>
The special server name “<literal>$hostname</literal>” has been supported
since 0.9.4.
</listitem>

<listitem>
A default server name value is an empty name “” since 0.8.48.
</listitem>

<listitem>
Named regular expression server name captures have been supported since 0.8.25.
</listitem>

<listitem>
Regular expression server name captures have been supported since 0.7.40.
</listitem>

<listitem>
An empty server name “” has been supported since 0.7.12.
</listitem>

<listitem>
A wildcard server name or regular expression has been supported for use
as the first server name since 0.6.25.
</listitem>

<listitem>
Regular expression server names have been supported since 0.6.7.
</listitem>

<listitem>
Wildcard form <literal>example.*</literal> has been supported since 0.6.0.
</listitem>

<listitem>
The special form <literal>.example.org</literal> has been supported since 0.3.18.
</listitem>

<listitem>
Wildcard form <literal>*.example.org</literal> has been supported since 0.1.13.
</listitem>

</list>
</para>

</section>

</article>