The server_name directive in Nginx is used to define which server block (virtual host) should process incoming requests based on the Host HTTP header. It allows hosting multiple domains or subdomains on a single server. Here's a detailed breakdown:

Syntax

server {
  listen 80;
  server_name example.com www.example.com;
  ...
}

Key Features

  1. Exact Matches
    List domain names explicitly:

    server_name example.com www.example.com;
    • Handles requests for example.com and www.example.com.

  2. Wildcard Patterns
    Use * to match subdomains or domain prefixes:

    server_name *.example.com;  # Matches blog.example.com, shop.example.com, etc.
server_name example.*;      # Matches example.com, example.net, etc.
    • Wildcards work only at the start or end of a domain segment (not in the middle).

  3. Regular Expressions
    Prefix patterns with ~ for complex matching:

    server_name ~^www\d+\.example\.com$;  # Matches www1.example.com, www2.example.com, etc.
server_name ~^(?<subdomain>.+)\.example\.com$;  # Captures subdomains into a variable.
    • Use ^ and $ to anchor matches.
    • Escape dots (.) with a backslash (\.).

  4. Default Server
    Specify a fallback server block when no Host header matches:

    listen 80 default_server;
server_name _;  # Catch-all (deprecated in some contexts; prefer `default_server` in `listen`).

Priority Order

Nginx resolves conflicts using this priority:

  1. Exact name (e.g., example.com).
  2. *Longest wildcard starting with `** (e.g.,*.example.com`).
  3. *Longest wildcard ending with `** (e.g.,mail.*`).
  4. First matching regular expression (in configuration file order).

Examples

# 1. Handle main domain + www
server {
  listen 80;
  server_name example.com www.example.com;
  root /var/www/example;
}

# 2. Catch all subdomains of example.com
server {
  listen 80;
  server_name *.example.com;
  root /var/www/subdomains;
}

# 3. Regex to match numeric subdomains (e.g., shop123.example.com)
server {
  listen 80;
  server_name ~^shop\d+\.example\.com$;
  root /var/www/shops;
}

# 4. Default server for unmatched requests
server {
  listen 80 default_server;
  server_name _;
  return 444;  # Close connection (Nginx-specific non-standard code)
}

Best Practices

  1. Set default_server Explicitly
    Avoid relying on the first server block as the default. Specify it in the listen directive:

    listen 80 default_server;

  2. Use Regex Sparingly
    Wildcards are more efficient than regular expressions.

  3. Test Configurations
    Use nginx -t to check syntax and nginx -s reload to apply changes.

  4. Handle www and Non-www
    Redirect between www and non-www versions for consistency:

    server {
 server_name example.com;
 return 301 https://www.example.com$request_uri;
}

Common Pitfalls

  • Overlapping Patterns: Ensure no conflicting server_name rules.
  • Case Sensitivity: Domains are matched case-insensitively (e.g., EXAMPLE.COM works).
  • Missing Host Header: Requests without a Host header (e.g., HTTP/1.0) go to the default server.

By mastering server_name, you can efficiently manage multiple domains and subdomains on a single Nginx instance.