Why use the listen directive?

Nginx will use one or more listen directives to find out if any match the client request. If so nginx will use this server block. The details of the direction may contain:

  • An IPv4 port e.g. 8080;
  • An IPv6 port e.g. [::]:8080;
  • An IPv4 address and port e.g.;
  • An IPv6 address and port e.g. [::1]:8080;
  • A unix socket e.g. unix:/var/run/nginx.sock;

Wrinkles to watch for

Listen can have lots of extra parameters. It’s not just about an IP address and/or port. The more commonly seen are:

  • ssl. In this case nginx will expect to find ssl certificates and keys defined elsewhere in the server block
  • http2. Note that http2 normally uses ssl, so both of these parameters would be expected to occur together.
  • default_server. This parameter tells nginx to use that server block as the default for that IP address: port pair.
  • ipv6only. Nginx can be told to ignore IPv4 by setting this to “on”.

The Listen directive can be missed out. In this case defaults have been hardcoded. This doesn’t feel like good practice – as it hides what’s happening.

  • If nginx is running with superuser privileges port 80 is used
  • If nginx is NOT running with superuser privileges port 8000 is used.

How to troubleshoot?

Listen is one of the early directives you have to get working. Proceed stepwise

  1. Make sure the port is defined
  2. Make sure that any router or firewall will allow traffic to reach the machine and port defined.
  3. Try getting things working with http first.
  4. Only then consider proceeding to SSL and multiplexing.

Insights from others

Watch this space.

What directives are typically seen alongside this?




Here’s the official text on the nginx site