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

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 the caller (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)

Listening to "real" IPv6 addresses¶

Examples:

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

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

Listening to not specified addresses¶

Examples:

• 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 sysctl net.ipv6.bindv6only = 1, this will listen on IPv6 only, otherwise on IPv6 and IPv4:

Examples:

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

Recommended IPv6 setup¶

This works since 1.4.27 or sysctl net.ipv6.bindv6only = 1

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

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

# if you need ssl
$SERVER["socket"] == "0.0.0.0:443" { <here your ssl options> }
$SERVER["socket"] == "[::]:443" { <here your ssl options again> }

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

server.bind = "0.0.0.0" 
server.port = "443" 
$SERVER["socket"] == "0.0.0.0:443" { <here your ssl options> }
$SERVER["socket"] == "[::]:443" { <here your ssl options again> }

For HTTPS-only on wildcard addresses and listening only on port 443 (minimal; equivalent to above)

server.port = "443" 
$SERVER["socket"] == "0.0.0.0" { <here your ssl options> }
$SERVER["socket"] == "[::]" { <here your ssl options again> }

For HTTPS-only on wildcard addresses and listening only on port 443 (minimal; equivalent to above; for lightpd 1.4.46 and later)

server.port = "443" 
$SERVER["socket"] == "[::]" { ssl.engine = "enable" }
ssl.engine = "enable" 
# additional ssl.* options here, set once in global scope, rather than being repeated

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 behaviour 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.