NGINX listen directive: Explained with examples

Introduction

Understanding the listen directive in NGINX is essential for configuring servers to correctly handle incoming network traffic. This tutorial will delve into the listen directive, providing a clear explanation along with practical examples.

What is the listen Directive in NGINX

The listen directive is used within the server block of NGINX’s configuration to define what IP address and port combinations the server block should respond to. By default, if no listen directive is provided, NGINX listens on port 80, the standard port for HTTP.

Let’s go through the format of the listen directive:

listen <address>:<port> [<parameters>];
listen [<ipv6>]:<port> [<parameters>];

Note: When specifying an IPv6 address, it must be enclosed in square brackets ().

Basic Usage

To kick things off, let’s look at simple usages of the listen directive:

# Listen on the default HTTP port (80)
listen 80;

# Listen on port 8080
listen 8080;

# Listen on a specific IP and port
listen 192.168.1.1:8080;

# Listen on a specific IPv6 address and port
listen [2001:db8::1]:8080;

Listening on HTTPS

To configure NGINX to listen for HTTPS traffic, you specify port 443 and typically include the ssl parameter:

listen 443 ssl;

Setting Default Server

If you have more than one server block for the same port, you can specify which one should be the default with the default_server parameter:

listen 80 default_server;

Example: Consider a scenario where you want to host multiple domains on the same server. Configuring a default server can catch any unspecified server names:

server {
    listen 80 default_server;
    ... # other config
}

server {
    listen 80;
    server_name example.com;
    ... # other config specific to example.com
}

Listening on Multiple Ports or Addresses

NGINX can listen on multiple ports or IP addresses. Each listen directive specifies an additional port or IP to listen on.

listen 80;
listen 8080;
listen [2001:db8::1];

Advanced Parameters

The listen directive also accepts a variety of parameters for more nuanced control. Some of these include:

• bind – Binds to the specified address and port, will cause to fail if the address is not available.
• ipv6only=on|off – For IPv6 addresses, allows listening for IPv6 connections exclusively.
• ssl – Enables SSL for the given listening port.
• spdy – Enables the SPDY protocol on this port.
• http2 – Enables HTTP/2 on this port (replacing spdy, which is deprecated).
• reuseport – Enables port reuse, which can improve scalability and performance.

Here’s how you might use these parameters: <code> listen 443 ssl http2; listen [2001:db8::1]:443 ssl http2; listen 80 reuseport; listen 80 default_server reuseport; </code>

Examples in Practice

Now that we’ve covered the directive and parameters, let’s look at some practical examples and explanations.

Important: Remember that changes to NGINX configuration files must be followed by a configuration test with nginx -t, and a restart or reload of the NGINX service with systemctl restart nginx or nginx -s reload. These steps ensure your configuration is valid and the server applies the new settings.

Example 1: Basic Web Server

server {
    listen 80;
    server_name example.com;
    root /var/www/example.com;
    # Other configuration settings...
}

In this example, the server block is set to listen on port 80 for HTTP traffic directed to example.com.

Example 2: Serving an HTTPS Site

server {
    listen 443 ssl default_server;
    server_name example.com;
    ssl_certificate /etc/nginx/ssl/example.com.crt;
    ssl_certificate_key /etc/nginx/ssl/example.com.key;
    root /var/www/example.com;
    # Other SSL settings and configurations...
}

Here the server block is configured to listen on port 443 with SSL for HTTPS connections as the default server for IP and port combination.

Example 3: Complex Configuration with Different Ports and Protocols

For a more complex example that deals with multiple domains, ports, IP addresses, and protocols consider the following configuration:

server {
    # Primary server block listening on HTTPS
    listen 443 ssl http2;
    server_name domain1.com;
    # SSL configuration
}

server {
    # Secondary server block listening on another port
    listen 1443 ssl http2;
    server_name domain2.com;
    # SSL configuration
}

server {
    # Additional server block for IPv6
    listen [2001:db8::1]:443 ssl http2;
    server_name domain3.com;
    # SSL configuration
}

In this complex configuration, there are server blocks configured for specific domain names, listening on different ports and IP versions, all using SSL with HTTP/2 enabled.

Conclusion

With the examples provided, from a basic setup to more complex scenarios, it’s clear how the NGINX listen directive is used to define the way your server listens to incoming network traffic. Adjusting these configurations tailors your server’s behavior to your specific requirements, whether you’re managing a simple site or a complex web application architecture.