IPv6-Config » History » Revision 10
Revision 9 (gstrauss, 2017-02-02 14:05) → Revision 10/12 (gstrauss, 2017-02-02 14:08)
h1. IPv6-Config
h2. Background
By default, lighttpd listens to the IPv4 wildcard (INADDR_ANY) on port 80 ("0.0.0.0:80") if neither <code>server.bind</code> or <code>server.port</code> are set. To change the default port, set <code>server.port</code>
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)
h2. 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.
h2. 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.
h2. 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" { ... }@
h2. Recommended IPv6 setup
This works since 1.4.27 or @sysctl net.ipv6.bindv6only@ = 1
<pre>
# 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> }
</pre>
For HTTPS-only on wildcard addresses and listening only on port 443
<pre>
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> }
</pre>
For HTTPS-only on wildcard addresses and listening only on port 443 (minimal; equivalent to above)
<pre>
#server.bind = "0.0.0.0" # (default; implied)
server.port = "443"
$SERVER["socket"] == "0.0.0.0" { <here your ssl options> }
$SERVER["socket"] == "[::]" { <here your ssl options again> }
</pre>
For HTTPS-only on wildcard addresses and listening only on port 443 (minimal; equivalent to above; for lightpd 1.4.46 and later)
<pre>
#server.bind = "0.0.0.0" # (default; implied)
server.port = "443"
$SERVER["socket"] == "[::]" { ssl.engine = "enable" }
ssl.engine = "enable"
# additional ssl.* options here, set once in global scope, rather than being repeated
</pre>
h2. 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.