NGINX: Using wildcards in server_name directive

Introduction

Understanding the server_name directive in NGINX and its utilization of wildcards is pivotal for managing server blocks effectively. In this in-depth tutorial, we’ll explore various ways to leverage wildcards in the server_name directive to enhance the flexibility and manageability of your server configurations.

server_name Directive

NGINX is a powerful, open-source web server that also serves as a reverse proxy, HTTP cache, and load balancer. One of the key features of NGINX is its ability to host multiple domains or subdomains on a single server, which is done through the server_name directive within server blocks. This capability allows NGINX to determine which server block to use for a given request. Wildcards can be used within the server_name to specify multiple domain names or subdomains dynamically.

Before diving into wildcards, let’s review the syntax for the server_name directive:

server {
    server_name domain.com www.domain.com;
}

In this example, NGINX will match either domain.com or www.domain.com. However, with wildcards, specifying a broader range of domain names is possible.

Basic Wildcards Usage

A wildcard character, represented by an asterisk (*), can match any number of characters. There are two ways to use wildcards:

• Prefix Wildcards: Placed at the beginning of a domain component to catch all subdomains.
• Suffix Wildcards: Placed at the end of a domain component to match different domain endings.

Here are examples for both:

server {
    server_name *.domain.com;
}

server {
    server_name domain.*;
}

The first server block catches any subdomain of domain.com, such as blog.domain.com, shop.domain.com, etc. The second block matches domain.com, domain.net, domain.org, and so on.

Using Wildcards for Subdomains

Prefix wildcards are commonly used for managing multiple subdomains efficiently. Let’s take a more detailed look:

server {
    server_name *.example.com;
}

With this configuration, NGINX will serve the same content for any subdomain of example.com. This setup is particularly handy for SaaS businesses that provide each customer with a personalized subdomain.

Advanced Wildcard Configurations

NGINX also allows for complex patterns that utilize wildcards in various parts of the server_name. The following example illustrates a sophisticated approach:

server {
    server_name www.*.example.com;
}

This configuration would respond to subdomains that include a prefix to the main domain, such as www.blog.example.com or www.shop.example.com.

However, keep in mind that NGINX processes these wildcard expressions from right-to-left and looks for a direct match before attempting to match wildcards. This behavior means that if you define a direct match for a specific domain alongside wildcard entries, the direct match will take precedence.

Regular Expressions as Wildcards

Besides simple wildcard characters, NGINX also supports full POSIX regular expressions. This extends the power of server_name matching with exact patterns:

server {
    server_name ~^www\..+\..+;
}

By prefixing the domain pattern with ~, we’re specifying that the pattern is a regular expression. In the above example, NGINX recognizes domains that begin with ‘www.’ and contain at least two dots, which effectively matches all ‘www.’ subdomains regardless of top-level and second-level domain names.

Note when using regular expressions, the first matching server block is used by NGINX, so it’s crucial to arrange them carefully within your configuration files.

Best Practices with Wildcards

Here are some helpful tips when using wilcards in the server_name directive:

• Explicitly define server blocks for your primary domain names before using wildcards.
• Limit the use of wildcards to avoid potential conflicts and maintain clear server block hierarchies.
• Utilize NGINX’s server block ordering to prioritize matches. Direct matches should be placed before wildcard entries.

Testing Your NGINX Configuration

Whenever you modify your NGINX configuration, it’s essential to test the changes before applying them:

sudo nginx -t

This command checks the syntax of your configuration files. If the test passes, you can safely reload NGINX to apply the changes:

sudo systemctl reload nginx

If you encounter errors, the nginx -t command will provide messages to help diagnose the issue.

Conclusion

By strategically employing wildcards in the server_name directive, you can design more versatile and scalable NGINX server blocks. Remember to follow best practices and validate your configurations to ensure the reliability and efficiency of your server. Refined wildcard utilization can lead to a much cleaner and better-organized server landscape.