What is ngx_stream_core_module ?

In the world of Nginx, there is a core module called ngx_stream_core_module that allows you to harness the power of stream proxy and load balancing. This module, available since version 1.9.0 of Nginx, is not enabled by default, but with the right configuration, it can revolutionize the way you handle stream connections.

With the ngx_stream_core_module, you can effortlessly set up stream proxy servers and achieve efficient load balancing, ensuring a smooth and reliable streaming experience for your users. Whether you need to handle stream SSL/TLS, proxy protocols, or stream proxy buffering, this module has got you covered.

If you are looking to take advantage of the ngx_stream_core_module and unlock its full potential, understanding its configuration directives and embedded variables is key. By leveraging these tools, you can optimize your stream server setup and streamline your performance.

In this article, we will delve deeper into the ngx_stream_core_module, exploring its configuration, example setups, common issues, and even compare it with alternative solutions like HAProxy. By the end, you will have a comprehensive understanding of this powerful Nginx stream module, equipped with the knowledge to enhance your stream proxy and load balancing capabilities.

Key Takeaways:

• The ngx_stream_core_module in Nginx enables robust stream proxy and load balancing capabilities.
• It provides configuration directives for setting up stream servers and optimizing performance.
• Embedded variables offer valuable information about connections and servers.
• Common issues like connection termination and client IP forwarding can be resolved.
• Compared to HAProxy, ngx_stream_core_module offers a lightweight and efficient solution within the Nginx ecosystem.

Example Configuration Directives

The ngx_stream_core_module provides several configuration directives that are essential for setting up the stream proxy and load balancing in Nginx. These directives allow you to fine-tune your server settings and optimize the performance of your stream servers. Below are some of the key directives:

Directive	Description
1 listen	Sets the address and port where the server will accept connections.
1 preread_buffer_size	Specifies the size of the preread buffer, determining how much data is read ahead before forwarding the stream to the upstream server.
1 preread_timeout	Specifies the timeout for the preread phase, defining how long to wait for the preread buffer to fill before forwarding the stream.
1 proxy_protocol_timeout	Sets the timeout for reading the PROXY protocol header, which allows reverse proxies to pass the original client’s IP address to the upstream server.
1 resolver	Configures the name servers used to resolve upstream server addresses, allowing Nginx to perform DNS resolution for the stream server.
1 resolver_timeout	Sets the timeout for name resolution, defining how long Nginx waits for a response from the resolver.
1 server	Sets the configuration for a specific stream server, including the listen address, proxy settings, and other server-specific options.
1 stream	Provides the configuration file context for the stream server directives, allowing you to define stream server blocks and their respective settings.
1 tcp_nodelay	Enables or disables the use of the TCP_NODELAY option, which disables the Nagle algorithm to improve response time for interactive applications.
1 variables_hash_bucket_size	Sets the bucket size for the variables hash table, which is used for storing and accessing variables in the stream configuration.
1 variables_hash_max_size	Sets the maximum size of the variables hash table, determining the number of buckets in the hash table.

These configuration directives provide a robust set of options for customizing the behavior of your stream servers in Nginx. Understanding how to properly configure and optimize these directives is key to building a highly performant and reliable streaming infrastructure.

Example Configuration

Configuring the ngx_stream_core_module involves setting up upstream servers, such as backend and dns, and specifying various parameters to optimize performance and connectivity. Let’s take a look at an example configuration:

Upstream Servers

To configure upstream servers, you can use the

directive. Here’s an example:

upstream backend {
server backend1.example.com:8080;
server backend2.example.com:8080;
}

In this example, we have defined an upstream block named “backend” with two server addresses. The ngx_stream_core_module will distribute incoming streams between the specified backend servers for load balancing.

Timeouts

Timeouts are essential parameters that control client and backend server connections. The following example shows how to define the

and

directives:

proxy_connect_timeout 5s;
proxy_timeout 30s;

In this configuration, the

sets the maximum time to establish a connection with the backend server, while the

defines the amount of time the client will wait for a response from the server before timing out.

Proxy Pass

The

directive is used to point the incoming stream to the specified upstream server. Here’s an example:

location / {
proxy_pass http://backend;
}

In this configuration, the stream will be forwarded to the “backend” upstream server defined earlier. The ngx_stream_core_module will handle the load balancing and proxying of the incoming stream.

By combining upstream servers, timeouts, and the proxy_pass directive, you can create a robust and efficient configuration using the ngx_stream_core_module.

Directives

In this section, I will provide detailed information about each of the directives mentioned in the previous section. I will cover the syntax, default values, and context for each directive. Understanding these directives is crucial for configuring the ngx_stream_core_module effectively.

Listen

The

directive sets the address and port where the server will accept connections. It is used to define the server’s listening address and port. By default, it listens on all IPv4 and IPv6 addresses. Here is the syntax:

1	listen address[:port] [default] [bind]

The

parameter specifies the IP address or hostname to listen on.
The

parameter specifies the port number to listen on. If not specified, the default port for the protocol is used.

Preread_buffer_size

The

directive sets the size of the preread buffer. This buffer is used to read data from a client before making a decision on which server to pass the connection to. Here is the syntax:

1	preread_buffer_size size

The

parameter specifies the size of the buffer. It can be specified in bytes, kilobytes (K), megabytes (M), or gigabytes (G).

Preread_timeout

The

directive specifies the timeout for the preread phase. This phase occurs before the server has received the full client request and is used for protocol detection and routing decisions. Here is the syntax:

1	preread_timeout timeout

The

parameter specifies the timeout duration. It can be specified in milliseconds (ms), seconds (s), minutes (m), or hours (h).

Proxy_protocol_timeout

The

directive sets the timeout for reading the PROXY protocol header. The PROXY protocol is used to pass client connection information to backend servers when using a proxy. Here is the syntax:

1	proxy_protocol_timeout timeout

The

parameter specifies the timeout duration. It can be specified in milliseconds (ms), seconds (s), minutes (m), or hours (h).

Resolver

The

directive configures the name servers used to resolve upstream server addresses. It specifies the IP address or domain name of the DNS resolver. Here is the syntax:

1	resolver address [valid=time] [ipv6=on|off]

The

parameter specifies the IP address or domain name of the DNS resolver.
The

parameter specifies the validity period of the DNS responses in seconds.
The

parameter enables or disables IPv6 addresses resolution.

Resolver_timeout

The

directive sets the timeout for name resolution performed by the resolver directive. It specifies the maximum time to wait for a response from the DNS resolver. Here is the syntax:

1	resolver_timeout timeout

The

parameter specifies the timeout duration. It can be specified in milliseconds (ms), seconds (s), minutes (m), or hours (h).

Server

The

directive sets the configuration for a server. It specifies the IP address or hostname, port, and other parameters for the server. Here is the syntax:

1	server address[:port] [parameters]

The

parameter specifies the IP address or hostname of the server.
The

parameter specifies the port number of the server.

Stream

The

directive provides the configuration file context for the stream server directives. It encapsulates the configuration for the stream server. Here is the syntax:

1	stream { ... }

The

represents the configuration directives specific to the stream server. Inside the

block, you can configure multiple

blocks to define different servers or upstreams.

Tcp_nodelay

The

directive enables or disables the use of the TCP_NODELAY option. Enabling TCP_NODELAY reduces the delay in sending packets but may increase the overall network traffic. Here is the syntax:

1	tcp_nodelay on|off

Setting it to

enables TCP_NODELAY option, while

disables it.

Variables_hash_bucket_size

The

directive sets the bucket size for the variables hash table. This hash table is used to store variables and their values for efficient lookup. Here is the syntax:

1	variables_hash_bucket_size size

The

parameter specifies the size of the bucket. It should be a power of 2.

Variables_hash_max_size

The

directive sets the maximum size of the variables hash table. This determines the number of variables that can be stored in the hash table. Here is the syntax:

1	variables_hash_max_size size

The

parameter specifies the maximum size of the hash table. It should be a power of 2.

Embedded Variables

The ngx_stream_core_module in Nginx provides support for embedded variables, which allow users to access valuable information about the connection and server. These variables play a crucial role in stream proxy and load balancing configurations, aiding in customization and troubleshooting processes. Understanding and utilizing these embedded variables can greatly enhance the functionality and efficiency of your Nginx setup.

Here are some essential embedded variables provided by the ngx_stream_core_module:

• binary_remote_addr: This variable stores the binary representation of the client’s IP address.
• bytes_received: The bytes_received variable represents the total number of bytes received from the client.
• bytes_sent: This variable indicates the total number of bytes sent to the client.
• connection: The connection variable stores the connection number assigned by Nginx.
• hostname: This variable holds the hostname requested by the client in the stream server configuration.
• msec: The msec variable represents the current time in milliseconds.
• nginx_version: This variable contains the version of Nginx being used.
• pid: The pid variable holds the process ID of the Nginx worker process handling the connection.
• protocol: This variable represents the protocol used for the connection, such as TCP or UDP.
• proxy_protocol_addr: The proxy_protocol_addr variable stores the client’s IP address received via the PROXY protocol.
• proxy_protocol_port: This variable indicates the client’s port number when using the PROXY protocol.

These embedded variables offer valuable insights into the connection and can be utilized within the configuration to perform various tasks, such as logging, access control, or dynamic routing based on specific characteristics of the stream connection. By leveraging these embedded variables effectively, you can optimize your Nginx stream proxy and load balancing setup to cater to your specific needs.

Example Usage

One of the practical use cases for embedded variables is to implement custom access control or rate limiting based on the binary_remote_addr variable. By examining the client’s IP address stored in this variable, you can make informed decisions about granting or restricting access to certain resources or applying specific policies.

Embedded Variable	Description
binary_remote_addr	Binary representation of the client’s IP address
bytes_received	Total number of bytes received from the client
bytes_sent	Total number of bytes sent to the client
connection	Connection number assigned by Nginx
hostname	Hostname requested by the client in the stream server configuration
msec	Current time in milliseconds
nginx_version	Version of Nginx being used
pid	Process ID of the Nginx worker process handling the connection
protocol	Protocol used for the connection (e.g., TCP or UDP)
proxy_protocol_addr	Client’s IP address received via the PROXY protocol
proxy_protocol_port	Client’s port number when using the PROXY protocol

Common Issues and Solutions

When using the ngx_stream_core_module, users may encounter common issues that can disrupt the proper functioning of their stream servers. Two such issues include connection termination and the forwarding of the client IP address. However, there are solutions available to address these problems effectively.

Connection Termination

In some cases, when using process managers like pm2 that automatically restart the node.js service, connections may be forcibly terminated. This can lead to disruptions in the stream service, affecting the user experience. However, this issue can be resolved by configuring the process manager to allow for graceful termination.

“By configuring the process manager to allow for graceful termination, you can ensure that connections are properly closed before the service restarts, minimizing interruptions and maintaining the seamless flow of data.”

Client IP Forwarding

Another common issue relates to the forwarding of the client IP address. When using the ngx_stream_core_module, it is essential to have accurate information about the client’s IP address to enable effective server-side processing. However, this information may not be preserved by default, leading to complications in tracking and identifying client requests.

To solve this issue, the ngx_stream_core_module provides the $remote_addr variable, which contains the client’s IP address. By using this variable in the configuration, you can ensure that the client’s IP address is correctly forwarded and accessible for any necessary processing or logging.

“By utilizing the $remote_addr variable provided by the ngx_stream_core_module, you can accurately track and handle client requests, gaining valuable insights into your stream server’s traffic and improving your monitoring and analysis capabilities.”

The image above visually represents the common issues faced by users while using the ngx_stream_core_module and highlights the importance of addressing these problems to ensure smooth stream server operations.

Comparison with HAProxy

Users looking for an alternative to the ngx_stream_core_module may consider using HAProxy. While HAProxy offers features such as advanced load balancing algorithms, it also has its own limitations.

When it comes to stream proxy and load balancing within the Nginx ecosystem, the ngx_stream_core_module provides a lightweight and efficient solution. It is specifically designed to handle stream connections with ease and offers features like SSL/TLS support, proxy protocols, and buffering.

HAProxy, on the other hand, is known for its robust load balancing capabilities and has been widely used in various scenarios. It excels in handling high traffic and complex network environments.

However, it is important to note that HAProxy may require additional configuration and setup compared to the ngx_stream_core_module. Nginx stream module eliminates the need for deploying an additional load balancing solution, making it a more cost-effective choice.

Here is a comparison of ngx_stream_core_module and HAProxy:

ngx_stream_core_module

• Lightweight and efficient solution for stream proxy and load balancing
• SSL/TLS support for secure connections
• Proxy protocols for enhanced compatibility
• Stream buffering for improved performance
• Integrated with Nginx, eliminating the need for an additional load balancing solution

HAProxy

• Robust load balancing capabilities
• Advanced load balancing algorithms
• Widely used in high traffic and complex network environments
• Requires additional configuration and setup compared to the ngx_stream_core_module
• Potentially higher cost due to the need for an additional load balancing solution

Considering the specific requirements and constraints of your project, it is important to evaluate the capabilities and limitations of the ngx_stream_core_module and HAProxy to make an informed decision.

Conclusion

In conclusion, the ngx_stream_core_module in Nginx offers a range of essential capabilities for stream proxy and load balancing. With its support for SSL/TLS, proxy protocols, buffering, and more, it ensures efficient handling of stream connections. By understanding the configuration directives and utilizing embedded variables, administrators can optimize the setup and enhance the performance of their stream servers.

While alternative solutions such as HAProxy exist, the ngx_stream_core_module remains a powerful and reliable choice for stream proxy and load balancing within the Nginx ecosystem. Its lightweight design and seamless integration with Nginx make it an attractive option for handling and managing streaming traffic.

Overall, the ngx_stream_core_module offers numerous benefits, including improved scalability, enhanced security, and simplified configuration. Whether it’s for streaming applications, real-time communication services, or even IoT devices, Nginx with the ngx_stream_core_module has proven to be a versatile solution that meets the demands of modern network infrastructure.

FAQ

What is the ngx_stream_core_module?

The ngx_stream_core_module is a core module in Nginx that enables robust stream proxy and load balancing capabilities.

When was the ngx_stream_core_module introduced?

The ngx_stream_core_module has been available since version 1.9.0 of Nginx.

Is the ngx_stream_core_module enabled by default?

No, the ngx_stream_core_module needs to be enabled with the –with-stream configuration parameter.

What are some key configuration directives provided by the ngx_stream_core_module?

Some key directives include listen, preread_buffer_size, preread_timeout, proxy_protocol_timeout, resolver, resolver_timeout, server, stream, tcp_nodelay, variables_hash_bucket_size, and variables_hash_max_size.

How can I set up upstream servers using the ngx_stream_core_module?

You can set up upstream servers by defining them as backend and dns and using the proxy_pass directive to forward the stream to the specified upstream server.

What are embedded variables and how can I use them with the ngx_stream_core_module?

Embedded variables are variables that provide specific details about the connection and server. They can be used in the configuration to access information such as the client’s IP address, connection details, and server information.

What are some common issues users may encounter with the ngx_stream_core_module?

Some common issues include connection termination when using process managers like pm2 and difficulties in forwarding the client IP address.

How does the ngx_stream_core_module compare to HAProxy?

While HAProxy may offer some advanced load balancing algorithms, the ngx_stream_core_module provides a lightweight and efficient solution for stream proxy and load balancing within the Nginx ecosystem.

Source Links

• http://nginx.org/en/docs/stream/ngx_stream_core_module.html