Project

General

Profile

IPv6-Config » History » Revision 11

Revision 10 (gstrauss, 2017-02-02 14:08) → Revision 11/12 (gstrauss, 2021-07-17 22:09)

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> 

 *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. 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. 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: 

 <pre> 
 # 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> 
 </pre> 

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

 <pre> 
 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" 
 </pre> 


 h2. Listening to "real" IPv6 addresses 

 Examples (IPv6 localhost [::1]): Examples: 

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

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


 

 h2. Listening to non-specified not specified addresses (wildcards) 

 Examples (wildcard addresses): Examples: 
 * not setting @server.bind@ 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 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 Linux @sysctl net.ipv6.bindv6only@ = 1, this will listen on IPv6 only.    If not, this listens only, otherwise on both IPv6 and IPv4: 

 Examples (wildcard addresses): 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 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.bind = ""@ 
 @server.use-ipv6 ""; server.use-ipv6 = "enable"@ "enable" 
 @$SERVER["socket"] * $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"@ 
 "localhost"@; @server.use-ipv6 = "enable"@ 
 * @$SERVER["socket"] == "[::]:443" {    }@ 
 * @$SERVER["socket"] == "localhost:443" { server.use-ipv6 = "enable" }@ 

 You can restore the old behavior 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.