Recently, while exploring the Nginx test environment, I encountered a less common Nginx error, as shown below:

[root@test conf]# nginx -t

nginx: [emerg] could not build server_names_hash, you should increase server_names_hash_bucket_size: 64

nginx: configuration file /usr/local/openresty/nginx/nginx/conf/nginx.conf test failed

When Nginx starts or rereads the configuration, it uses a cache to process some static data sets (such as server name, MIME type, etc.) faster. types, etc. (you've probably encountered this when configuring Nginx). This is stored in a cache block (cached in a storage mechanism, between memory and CPU registers, relatively close to the CPU. Modern CPUs encapsulate this inside the CPU, such as L1, L2, and L3. Their characteristic is speed, faster than memory but slower than registers). The size of this cache block is controlled by the parameter server_names_hash_bucket_size. The default size varies depending on the physical CPU, usually being a power of 2. When increasing the size, adjust the value based on the CPU level.

1. Error Cause One (Most People Encounter):

Root Cause One: Your server_name is really too long

Your domain name is indeed too long, exceeding the default value. In this case, you can only increase the value:

http { server_names_hash_bucket_size 64; ..... }

2. Error Cause Two (For Those Who Have a Hard Life, Not a Hard Job):

Root Cause Two: Config Mistake

Sometimes, due to a misconfiguration, the domain name isn't actually that long; it's simply a matter of mixing up the various configuration syntaxes. For example, you separated multiple domain names with commas instead of spaces, and unfortunately, you're working a 996 hour shift and may not be able to pinpoint the problem even after a long time. The following error will also result in the same error. Don't ask me how I know this, because I encountered this exact thing on an old test server with an abandoned domain name...

server { server_name www.test1.com, www.test2.com, www.test3.com, www.test4.com; }

At this point, there's no need to change the value of server_names_hash_bucket_size; simply fix the configuration error.

3. Test sample (Try it by yourself)

➜ ~ sudo cat /etc/nginx/conf.d/test.com.conf server { listen 80;

just for test

#server_name www.1111.2222.3333.4444.5555.6666.7777.8888.com; # too long server_name test, fail #server_name www.1111.2222.3333.4444.5555.com; # not so long, ok #server_name www.test1.com wwww.test2.com www.test3.com www.test4.com; # multi server_name, ok #server_name www.test1.com, wwww.test2.com, www.test3.com, www.test4.com; # mistake config, comma separated, multi server_name, fail }

As shown above, simple tests in different situations will deepen your understanding.

4. Background Knowledge

What is server_names_hash_bucket_size? Nginx official documentation:

Syntax: server_names_hash_bucket_size size; Default: server_names_hash_bucket_size 32|64|128; Context: http Sets the bucket size for the server names hash tables. The default value depends on the size of the processor’s cache line. Details on setting up hash tables are provided in a separate document.

What is the processor’s cache line?

It could be left up to the programmer or compiler to determine what data should be placed in the cache memories, but this would be complicated since different processors have different numbers of caches and different cache sizes. It would also be hard to determine how much of the cache memory to allocate to each program when several programs are running on the same processor.

Instead the allocation of space in the cache is managed by the processor. When the processor accesses a part of memory that is not already in the cache it loads a chunk of the memory around the accessed address into the cache, hoping that it will soon be used again.

The chunks of memory handled by the cache are called cache lines. The size of these chunks is called the cache line size. Common cache line sizes are 32, 64 and 128 bytes.

A cache can only hold a limited number of lines, determined by the cache size. For example, a 64 kilobyte cache with 64-byte lines has 1024 cache lines.

nginx hashes related instructions:

To quickly process static sets of data such as server names, map directive’s values, MIME types, names of request header strings, nginx uses hash tables. During the start and each re-configuration nginx selects the minimum possible sizes of hash tables such that the bucket size that stores keys with identical hash values does not exceed the configured parameter (hash bucket size). The size of a table is expressed in buckets. The adjustment is continued until the table size exceeds the hash max size parameter. Most hashes have the corresponding directives that allow changing these parameters, for example, for the server names hash they are server_names_hash_max_size and server_names_hash_bucket_size.

The hash bucket size parameter is aligned to the size that is a multiple of the processor’s cache line size. This speeds up key search in a hash on modern processors by reducing the number of memory accesses. If hash bucket size is equal to one processor’s cache line size then the number of memory accesses during the key search will be two in the worst case — first to compute the bucket address, and second during the key search inside the bucket. Therefore, if nginx emits the message requesting to increase either hash max size or hash bucket size then the first parameter should first be increased.

Wikipedia cache:

A CPU cache is a hardware cache used by the central processing unit (CPU) of a computer to reduce the average cost (time or energy) to access data from the main memory.[1] A cache is a smaller, faster memory, located closer to a processor core, which stores copies of the data from frequently used main memory locations. Most CPUs have a hierarchy of multiple cache levels (L1, L2, often L3, and rarely even L4), with different instruction-specific and data-specific caches at level 1.

Data is transferred between memory and cache in blocks of fixed size, called cache lines or cache blocks. When a cache line is copied from memory into the cache, a cache entry is created. The cache entry will include the copied data as well as the requested memory location (called a tag).

Memory hierarchy: