Recommended Free Tools
iTechGuides is reader-supported. When you buy through links on our site, we may earn an affiliate commission. As an Amazon Associate I earn from qualifying purchases. Learn more
Need a server to try this on? Antihost offers Linux VPS plans with NVMe storage, full root access and a 14-day free trial.
server_name assigns host names to an Nginx server block. When multiple blocks listen on the same IP address and port, Nginx compares the request’s host information with those names and chooses the matching block. The listen directive determines which socket is eligible; server_name determines which name matches within that socket.
The role of server_name
An Nginx virtual server is a server { ... } configuration block. A typical site definition looks like this:
server {
listen 80;
server_name example.org www.example.org;
root /var/www/example;
}Here, listen 80 makes the block eligible for HTTP connections on port 80, while server_name says which host names the block serves. The first name, example.org, is the primary name; www.example.org is an additional name for the same virtual server.
Nginx documentation describes the directive this way: server names are defined with server_name and determine which server block is used for a request. If several blocks match the request’s address and port, Nginx tests the HTTP Host header against the names in those blocks.
#1 Best Overall
How Nginx chooses a server block
Server selection happens in stages. First, Nginx narrows the candidates by the local address and port from listen. It then compares the request’s host value with the server_name values in those candidates. If no name matches, the request goes to the default server for that address and port.
1. The request identifies a socket
A client connects to an IP address and port, such as port 80 for HTTP or port 443 for HTTPS. Every eligible server block must have a compatible listen directive. Two blocks listening on different ports do not compete with one another, even if they contain identical names.
2. Nginx compares the host name
For an HTTP request, the host normally comes from the Host header. For example, a request for https://shop.example.org/ carries shop.example.org as its host value. Nginx compares that value with the names declared in the candidate blocks.
3. The highest-priority name wins
When more than one declaration could match, Nginx searches these categories in order:
| Priority | Match type | Example | How conflicts are resolved |
|---|---|---|---|
| 1 | Exact name | example.org |
An exact match wins over wildcard and regular-expression matches. |
| 2 | Leading wildcard | *.example.org |
The longest matching wildcard beginning with an asterisk wins. |
| 3 | Trailing wildcard | mail.* |
The longest matching wildcard ending with an asterisk wins. |
| 4 | Regular expression | ~^userd+.example.org$ |
The first matching regular expression in configuration-file order wins. |
“Longest” applies within the relevant wildcard category. Regular expressions are considered only after exact and wildcard names, and their order in the loaded configuration matters.
Exact, wildcard and regular-expression names
Exact names
An exact name is the clearest and most predictable form:
Outdated Drivers Are Slowing You Down
One free scan finds every outdated or missing driver and matches the right update for your exact hardware.Free scan · exact hardware matchPC Slower Than It Used to Be?
A free scan shows the junk files, broken settings and background clutter dragging Windows down - then fixes them in one click.Free scan · Windows 10 & 11server {
listen 80;
server_name api.example.org;
root /srv/api;
}Only requests whose host is api.example.org match this name. If you also want www.api.example.org, list it explicitly or use an appropriate wildcard.
Leading wildcards
A wildcard at the beginning can cover subdomains:
server_name *.example.org;Wildcard placement is restricted. The asterisk must be at the beginning or end on a dot boundary; arbitrary patterns such as api.*.example.org are not valid wildcard names. If several leading wildcards match, Nginx uses the longest one.
Trailing wildcards
A name such as mail.* matches names beginning with mail.. Trailing wildcards are a separate precedence category from leading wildcards, so do not assume they compete as one combined list.
The shorthand .example.org
The special shorthand beginning with a dot matches both the bare domain and names below it:
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
server_name .example.org;This covers example.org as well as www.example.org. It is useful when the same content and policy apply to the apex domain and its subdomains.
Regular expressions
A regular-expression server name starts with ~ and uses PCRE syntax:
server_name ~^user[0-9]+.example.org$;Use ^ and $ when the expression is intended to match the entire host name. Escape literal dots because an unescaped dot in a regular expression matches any character. Since the first matching expression in configuration order wins, keep overlapping expressions ordered deliberately.
What happens when nothing matches
If the host does not match any server_name, or if the request has no host header, Nginx sends it to the default server for the selected address and port. The default is normally the first server listed for that socket. You can make the choice explicit by adding default_server to the relevant listen directive:
Quick wins for a faster PC:
Repair Windows errors before they cause bigger problemsFix Now →Scan for outdated or missing drivers - takes under a minuteDriver Scan →Clear out junk files and repair common Windows errorsFree Scan →Rank #3
server {
listen 80 default_server;
server_name _;
return 444;
}The block above is commonly used to reject unknown hosts. The important setting is default_server, not the underscore.
What server_name _; really means
An underscore is a conventional name that is unlikely to be a real domain. Nginx documentation explicitly notes that there is nothing special about this name. It is not a built-in catch-all token and does not, by itself, intercept every host.
To create a catch-all behavior, make the block the default for the socket:
server {
listen 80 default_server;
server_name _;
return 404;
}
server {
listen 80;
server_name example.org www.example.org;
root /var/www/example;
}In this arrangement, known names select the second block. Unknown or missing host values fall back to the first block because it is marked as the default. If another block already has default_server on the same address and port, Nginx will reject the duplicate configuration.
HTTPS: SNI and the later Host match
HTTPS adds a TLS decision before normal HTTP processing. During the TLS handshake, a client can send the target name through Server Name Indication (SNI). Nginx may use SNI to select a server configuration and certificate before an HTTP request exists. After the handshake, Nginx processes the request line and Host header and can select configuration again.
For that reason, the names covered by an HTTPS block, its certificate, and the names clients actually send should be consistent. A certificate for one host does not automatically make another host valid, and placing a name in an HTTP block does not configure its HTTPS listener.
server {
listen 443 ssl;
server_name example.org www.example.org;
ssl_certificate /etc/nginx/tls/example.crt;
ssl_certificate_key /etc/nginx/tls/example.key;
}If an HTTPS request appears to reach the wrong site, check both the SNI-selected TLS block and the later Host-based selection, as well as which block is default for port 443.
Rank #4
The first name and redirects
The first name in a server_name list is the primary server name. Nginx uses that primary name when it needs to construct an absolute redirect unless server_name_in_redirect changes the behavior.
server {
listen 80;
server_name example.org www.example.org;
server_name_in_redirect on;
return 301 https://example.org$request_uri;
}With server_name_in_redirect disabled, Nginx uses the request’s Host value when one is present. Choose the first name and redirect policy together so clients are sent to the canonical hostname you intend.
Practical configuration patterns
One site with an apex and a www name
server {
listen 80;
server_name example.org www.example.org;
root /var/www/example;
index index.html;
}Both names serve the same document root. If one should redirect to the other, use a separate block for the redirecting name and leave the content block with only the canonical name.
Separate applications on one address
server {
listen 80;
server_name app.example.org;
proxy_pass http://app_backend;
}
server {
listen 80;
server_name api.example.org;
proxy_pass http://api_backend;
}The two blocks can share an IP address because the host names distinguish them. Their listen values must still identify the same address and port for name-based selection to occur between them.
Catch-all plus named sites
server {
listen 80 default_server;
server_name _;
return 404;
}
server {
listen 80;
server_name site-a.example site-b.example;
root /srv/sites;
}This pattern gives unrecognized host values a deliberate response instead of exposing whichever site happens to be first in the file.
Free tools Windows power users keep installed
One-click scans. No signup required.
Why a request goes to the wrong virtual host
Work through the selection inputs in this order:
- Verify the destination port and address. Confirm that the request reaches the socket you configured. Port 80 and port 443 have independent server lists and defaults.
- Check the host actually sent. A typo, an unexpected port in the host header, or a client that omits the header can send the request to the default block.
- List every competing name. Look for an exact name that should win, a longer wildcard, or an earlier regular expression.
- Inspect the default. Find the first block for that socket and any
listen ... default_serverdeclaration. There must be only one default per address and port. - Check the loaded configuration, not only an edited file. Included files can add another server block or change regular-expression order. Validate with
nginx -tbefore reloading. - For HTTPS, check SNI and certificates. Confirm that the client sends the expected SNI name and that the certificate-serving block covers it.
- Reload after changes. A syntactically correct edit has no effect until the running Nginx process loads it.
When testing, send an explicit host to the intended address so DNS does not obscure the result. For example, an HTTP test can use curl -H 'Host: example.org' http://203.0.113.10/; use an address and host appropriate to your own environment.
Configuration limits and internationalized domains
Name-hash sizing
Nginx stores server names in hash tables. A very large or unusually long collection of names can produce startup errors about hash sizes. The reference directives server_names_hash_max_size and server_names_hash_bucket_size control those limits. Increase them only when Nginx’s error message indicates that the current values cannot accommodate the configured names, then test the complete configuration before reloading.
Internationalized domain names
Enter internationalized domain names in ASCII Punycode form in server_name. The form displayed to users and the ASCII form used in configuration are not necessarily identical; convert the domain correctly before adding it.
A compact decision checklist
- Does the block listen on the address and port receiving the request?
- Is the intended host listed exactly, or covered by the correct wildcard or regular expression?
- Could an exact name or longer wildcard take precedence?
- Are regular expressions anchored and ordered safely?
- Is the intended fallback block marked
default_server? - Are HTTPS SNI names, certificates and
server_namevalues aligned? - Is the primary name the one you want used in absolute redirects?
- Have you adjusted name-hash settings only when required by configuration-test errors?
- Are internationalized names written in Punycode?
Key takeaway
server_name is the host-name matching part of Nginx virtual-server selection. listen chooses the address-and-port group; Nginx then prefers exact names, the longest leading wildcard, the longest trailing wildcard, and finally the first matching regular expression. Unmatched requests use the socket’s default server, and server_name _; is merely a conventional label. Treat the listener, name precedence, default block, and (for HTTPS) SNI configuration as one system when diagnosing routing problems.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
