Introduction
The performance and reliability of a web server can hinge on many configuration settings. When it comes to NGINX, understanding the role and proper setting of server_names_hash_max_size and server_names_hash_bucket_size is significant for smooth operation, especially if you’re dealing with a large number of server names. In this article, we will delve into what these directives do, why they’re important, and how to use them in real-world scenarios.
What are server_names_hash_max_size and server_names_hash_bucket_size?
Before we launch into scenarios, let’s first understand what these directives are:
server_names_hash_max_size defines the maximum size of the server names hash tables. A hash table is a data structure used to store server names for rapid retrieval. When HTTP requests come into NGINX, it uses this hash table to quickly find the right server configuration based on the requested server name.
server_names_hash_bucket_size sets the size of each bucket in this hash table. Buckets are the base memory units within a hash table. In NGINX, the size should ideally be equal to one memory page, which is dependent on the processor’s architecture. The default value is 32 or 64 bytes, transparently aligned to the size of the processor’s cache line.
Why Do These Settings Matter?
They’re particularly important for websites hosting a significant amount of server names or server aliases. If NGINX’s hash table is too small to hold all of the server names, or if the size of one or more server names is larger than a single bucket, the server will refuse to start and will display an error stating the hash bucket or hash table is too small.
Exploring server_names_hash_max_size
To adjust the size of the hash table, add or edit the following line in your nginx.conf file inside the http block:
http {
server_names_hash_max_size 512;
}
This setting accepts a numerical value that dictates the maximum size for the hash tables. A larger server_names_hash_max_size allows you to host more server names because it increases the size of the hash tables. Conversely, NGINX starts slightly slower every time it’s restarted due to the increased time required to build a larger hash table.
Understanding server_names_hash_bucket_size
To tune the size of each bucket in your hash table, add or alter the following line in the nginx.conf configuration file:
http {
server_names_hash_bucket_size 128;
}
This setting is a bit more sensitive to change and should ideally be a number that is a multiple of your processor’s cache line size. While you may want to increase this to account for longer server names or a vast number of server aliases, setting this value without proper calculation can negatively impact performance.
Practical Examples
Example 1: Handling Many Domain Names
Imagine you’re hosting a shared hosting environment with hundreds of regularly accessed domain names. When each HTTP request hits your web server, NGINX needs to efficiently determine which server block matches the request. A low server_names_hash_max_size value might cause NGINX to fail. Here’s what you can do:
http {
server_names_hash_max_size 2048;
}
By increasing the server_names_hash_max_size, NGINX will have more room in its hash table to manage more server names.
Example 2: Long Server Names
If you encounter an error such as “could not build the server_names_hash, you should increase server_names_hash_bucket_size”, this typically means the bucket_size is too small for at least one of the server names. You can adjust it like this:
http {
server_names_hash_bucket_size 128;
}
By adjusting the server_names_hash_bucket_size to a higher value, NGINX can accommodate server names that have a lengthier byte-size representation.
As a rule of thumb, you should set server_names_hash_bucket_size to be equal or slightly higher than the size of the longest server name in your configuration.
Tuning & Optimization
To optimally tune your NGINX server, it’s advised to apply these directives concisely and within the scope of your application’s requirements. Making arbitrary changes can lead to unnecessary memory consumption or might have no effect if done incorrectly.
Monitoring & Inspection
When making changes to the NGINX configuration, always run nginx -t to test and make sure there are no configuration errors. Once the configuration is deemed accurate, reload NGINX with nginx -s reload.
Conclusion
The server_names_hash_max_size and server_names_hash_bucket_size configurations are a small yet crucial part of optimizing and ensuring the stability of an NGINX server that manages an abundance of server names. Start with the defaults, watch for errors during the server start, and make careful increments only when necessary. With the general understanding and practical examples provided above, you’re well-equipped to navigate these settings for your unique NGINX setup.
