IPv6-Config¶

Background¶

By default, lighttpd listens to the IPv4 wildcard (INADDR_ANY) on port 80 ("0.0.0.0:80") if neither server.bind or server.port are set. To change the default port, set server.port

Summary: explicitly specify IPv4 and IPv6 addresses (or wildcards) on separate lines (See "Recommended IPv6 setup" below)

For IPv6 wildcard "[::]" (in6addr_any) and v4-mapped IPv6 addresses (e.g. "::ffff:127.0.0.1"), there is a kernel socket option for IPPROTO_IPV6 called IPV6_V6ONLY, which causes the socket to be bound only to an IPv6 address, and not also to the IPv4 equivalent. If this socket option is not present for an address family that is AF_INET6 (IPv6), then whether on not the socket is bound only to an IPv6 address depends on the default configured for the kernel. In other words, on some systems, IPV6_V6ONLY will be forced on IPv6 sockets, whether or not IPV6_V6ONLY has been set by lighttpd. These include the default configurations of modern Debian Linux, FreeBSD, Mac OS X, and possibly others. On these systems, two separate socket directives are needed to have lighttpd listen on both IPv4 and IPv6 addresses, e.g. 0.0.0.0 and [::]. (See "Recommended IPv6 setup" below)

Recommended IPv6 setup¶

(For lighttpd 1.4.27 or later, or Linux OS sysctl net.ipv6.bindv6only = 1, or other OS equivalent)
To listen on all TCP addresses on the server:

# listen to IPv4
server.bind = "0.0.0.0" 
server.port = "80" 

# listen to IPv6
$SERVER["socket"] == "[::]:80" {  }

# SSL/TLS
$SERVER["socket"] == "0.0.0.0:443" { ssl.engine = "enable" }
$SERVER["socket"] ==    "[::]:443" { ssl.engine = "enable" }
# SSL/TLS options shared among $SERVER["socket"] with ssl.engine = "enable" 
#<shared ssl.* options>

For HTTPS-only on wildcard addresses and listening only on port 443

server.bind = "0.0.0.0"                                       # (default; implied)
server.port = "443" 
$SERVER["socket"] == "0.0.0.0:443" { ssl.engine = "enable" }  # (redundant with default)
$SERVER["socket"] ==    "[::]:443" { ssl.engine = "enable" }
# SSL/TLS options shared among $SERVER["socket"] with ssl.engine = "enable" 
#<shared ssl.* options>
ssl.engine = "enable" 

Listening to "real" IPv6 addresses¶

Examples (IPv6 localhost [::1]):

• server.bind = "[::1]"
• $SERVER["socket"] == "[::1]:80" { ... }

You are fine with these - they only listen to IPv6 in any case.

Listening to non-specified addresses (wildcards)¶

Examples (wildcard addresses):

• not setting server.bind at all, but using server.use-ipv6 = "enable" in the global context
• $SERVER["socket"] == ":80" { server.use-ipv6 = "enable" ... }

These configs listen on the IPv6 "any" address; depending on your system this may also accept IPv4 connections (default under Linux unless your distribution disabled it; check sysctl net.ipv6.bindv6only).
So such configs may break any time if the kernel default changes.

Listening to [::]¶

If you use 1.4.27+ or have Linux sysctl net.ipv6.bindv6only = 1, this will listen on IPv6 only. If not, this listens on both IPv6 and IPv4:

Examples (wildcard addresses):

• server.bind = "[::]"
• $SERVER["socket"] == "[::]:80" { ... }

Changes in 1.4.27¶

Since 1.4.27 lighttpd will set the "V6_ONLY" option for IPv6 sockets that were not empty hostname; i.e. these two will still use the system default for V6_ONLY as before:
server.bind = ""
server.use-ipv6 = "enable"
$SERVER["socket"] == ":443" { server.use-ipv6 = "enable" }

But for these cases lighttpd will only listen to IPv6 since 1.4.27 (or if sysctl net.ipv6.bindv6only is 1):
server.bind = "[::]"
server.bind = "localhost"
server.use-ipv6 = "enable"
$SERVER["socket"] "[::]:443" { }
$SERVER["socket"] "localhost:443" { server.use-ipv6 = "enable" }

You can restore the old behavior if you set server.set-v6only = "disable" in the associated block. Use of this option is not recommended as long-term solution, as we will probably remove it again after some versions.