Manual:IPv6 support

MediaWiki has traditionally identified anonymous users (those not logged in) by their IPv4 addresses, which were presumed to be globally unique. For the most part, this approach was valid, the primary exceptions being a few problematic ISP's which displayed all users as being behind a few known proxy servers instead of identifying them by their individual globally-unique IPv4 addresses.

At a time when globally-unique IPv4 address blocks remained freely available to ISP's, one IP address was likely to identify one user (or no more than one small local area network). Unfortunately, the last large blocks of IPv4 addresses (a /8, just over 16 million addresses) were issued on January 31, 2011 to regional Internet registries and will soon be depleted. The availability of new IPv4 space to ISP's has therefore been constrained, providers in the Asia-Pacific region now being allocated blocks of 1024 addresses instead of the formerly-unlimited quantities.

This leaves affected Internet providers with a few limited options. Carrier-grade NAT can be used to cause many users to appear to be coming from the same few IPv4 addresses - a likely short-term approach, but one which will cause problems for MediaWiki sites as blocking these addresses blocks an entire ISP's userbase. IPv6 transition mechanisms are another option, as is full IPv6 deployment. IPv6 can be used to obtain unique addresses for every user or every device from a huge pool of 2¹²⁸ possible IPv6 addresses.

As more than 95% of websites (as of 2011) support IPv4 only, soon these sites will be seeing the same few IPv4 addresses in Special:Recentchanges repeatedly - but, instead of one address representing one user, one IPv4 address will represent multiple users behind one NAT or one gateway. The only way to uniquely identify users from IP addresses will be to offer IPv6 alongside existing IPv4 on all domains. IPv6-aware web browsers, if provided with valid IPv4 and IPv6 paths to reach the same domain, will use IPv6 and continue to appear with globally-unique addresses in Special:RecentChanges on an IPv6-aware site.

As IPv6 users are not affected by IPv4 address blocking (and vice-versa), the risk of blocking a gateway's IPv4 address and all users behind it to stop spam or vandalism from one computer diminishes. Likewise, however, a single vandal using an entire LAN (that would otherwise be completely blocked by an IPv4 block in most cases) to constantly evade individual IPv6 blocks would have to be put under a range block, with similar amounts of collateral damage as if the vandal were using a shared IPv4.

IPv6 in MediaWiki

As of 2011, IPv6 addressing is supported in current versions of MediaWiki (1.17 and above). Earlier versions may have partial support but contain bugs; MediaWiki 1.9 will not handle IPv6 addresses at all.

MediaWiki itself is not tasked with listening for incoming IPv6 connections as this is done by the host Apache webserver or (on high-traffic sites) a web accelerator proxy such as Varnish.

MediaWiki does, however, record IP addresses for anonymous edits in Special:RecentChanges (and IPs for all edits in CheckUser). It also depends on IP addressing to block users, both in its own internal functionality and in that added by extensions. It is therefore essential that any IPv6 deployment allow MediaWiki to log valid external IPv6 addresses to recent changes (and not the IPv4 address of servers or gateways). This works, e.g. on zh-wiki you will see occasional anonymous edits from IPv6 addresses.

Blocking users also differs between IPv4 and IPv6 in that a typical IPv6 local area network is likely to be assigned not a single IPv6 address but a range of addresses (at least a /64 for a single router) with the lower 64 bits populated by the client computer. Blocking a single address (a /128) therefore may not suffice to block a persistent vandal, leading to more frequent use of range blocks to counter spam and vandalism.

The GlobalBlocking extension, accepts IPv6 addresses and ranges, but before a certain revision, blocks were not effective and did not show up in the extension's log unless a database schema modification was made.

IPv6 addresses

Because an IPv6 address can take on various forms (for example, 2001:db8:: and 2001:db8:0:0:: are the same address), MediaWiki expands all IPv6 addresses to their entire length (however, the number of digits in a single group between colons is always the minimum. For example 2001:db8:: expands to 2001:db8:0:0:0:0:0:0) and capitalizes lettered digits. This is done before parsing a search query for an IPv6 address' user page, user talk page, or contributions page, and for queries in CheckUser.

Installation and deployment

This description is aimed at users who control an entire server (be it virtual, dedicated or co-located). For users of shared webhosts, many of the tasks listed here are controlled not by clients but by hosting providers.

It also presumes IPv6 to already be configured on the server at the network and operating system level.

Apache direct-connection

On a high-traffic site (such as Wikipedia) the Apache server does not accept incoming connections from users directly but is located behind a reverse proxy server such as Squid or Varnish.

On a small site in which Apache is accepting direct connections from users, however, Apache will need to be configured to listen to both the external IPv4 and IPv6 ports on your server.

IPv6 addresses in httpd.conf must be surrounded in square brackets, as in the following example:

# Listen for IPv4 connections on one outside address
Listen 192.170.2.1:80

# Listen for IPv6 connections on one address
Listen [2001:db8::a00:20ff:fea7:ccea]:80 

In Apache 2 or above, the Listen, NameVirtualHost, and VirtualHost directives support IPv6 numeric address strings (e.g., "Listen [2001:db8::1]:8080").

Squid and Varnish reverse proxies

See also Squid or Varnish caching

On high-traffic sites, Apache httpd is normally configured behind a caching reverse proxy server such as Squid so that dynamic content may be served from the cache instead of being regenerated for each viewer.

A simple example (one Squid backed by one Apache webserver) would be:

Outside world

<--->

Server Squid accelerator w.x.y.z:80 [2001:db8:a:b:c:d:e:f]:80 <---> Apache webserver 127.0.0.1:80

Squid listens to all external addresses (IPv6 and IPv4), serves the page directly if it is in cache, forwarding any requests it cannot handle on its own (cache misses) to an Apache server (in this example, on the IPv4 loopback address on the same computer). As the connection between Squid and Apache is solely internal, it does not matter whether IPv4 (127.0.0.1) or IPv6 (::1) is used - but there is no purpose in using both except on externally-accessible interfaces.

Squid 3.1 and later support IPv6 addressing but must be configured to list all addresses on which Squid is to listen, ie:

# Listen for IPv4 connections on an outside address
http_port 192.170.2.1:80 vhost defaultsite=example.org

# Listen for IPv6 connections on various addresses
http_port [2001:db8::2]:80 vhost defaultsite=example.org
http_port [2001:db8::123:456]:80 vhost defaultsite=example.org

MediaWiki's configuration file (LocalSettings.php) does need to list all addresses used by reverse proxy or gateway servers to ensure these do not appear in Special:Recentchanges

$wgUseCdn = true;
$wgCdnServers = array('192.170.2.1');
$wgCdnServersNoPurge = array('127.0.0.1','2001:db8::2', '2001:db8::123:456');

Note that the cache 'purge' messages only need to be sent to each Squid once (even if it's listening on multiple addresses) and should not be sent to Apache at all (as it will only be logged as an error). Listing only one of the Squid addresses in $wgCdnServers and the others in $wgCdnServersNoPurge ensures this.

The same requirements (including indication of every address, IPv4 or IPv6, to be monitored) also apply to Varnish. Versions 2.1 or later of Varnish support IPv6; the list of addresses is supplied in the list of options in the format:

-a address[:port][,address[:port][...]

where the address can be a host name (“localhost”), an IPv4 dotted-quad (“127.0.0.1”), or an IPv6 address enclosed in square brackets (“[::1]”).

-a 192.170.2.1:80,[2001:db8::2]:80,[2001:db8::123:456]:80

should therefore be the Varnish equivalent of the Squid example listed above.

Similar considerations apply for other reverse-proxy web caching schemes, such as CloudFlare. IPv6 needs to be enabled at the cache server and in DNS, but there are no configuration changes on the origin servers. On CloudFlare (which is both a DNS and a content delivery network), simply selecting "Automatic IPv6: Full" on www.cloudflare.com/cloudflare-settings.html for each domain is enough to get a site with any current MediaWiki version up and running on IPv6. The origin servers do not need to be on an IPv6-aware host.

Domain name servers

Berkeley Internet Name Domain (BIND) daemon “named” supports IPv6 from version 9 onward, as do other rival DNS programmes.

While BIND is not in any way part of MediaWiki, it (or another Internet name server) will need to be configured to provide the addresses of your IPv6-aware MediaWiki site to your users once your system is ready for deployment.

To tell BIND to listen for IPv6 connections, edit the options section of named.conf to include the listen-on-v6{any;}; directive:

options {
        directory "/etc";
        pid-file "/var/run/named/named.pid";
        listen-on-v6{any;};
        };

The IPv4 and IPv6 addresses of your publicly available domains will need to be added to the *.hosts files for your nameserver; IPv6 are identified as IN AAAA while IPv4 are A records:

ipv6.example.org.   IN      AAAA    2001:db8::2
ipv4.example.org.   IN      A       192.170.2.1

IPv6-compatible software

This list indicates status of Internet-facing software typically installed on a deployed MediaWiki server; see the comparison of IPv6 application support for a more general list of all current IPv6-aware applications.

Note that only Internet-facing applications (which accept connections directly from users) need be made IPv6 aware. Services such as mysqld or memcached which perform back-end roles need not be both IPv4 and IPv6 aware as it is not desirable that these be accessible from any except the localhost or local area network for security reasons.

Application	Minimum version	IPv6-specific configuration (if required)
Apache httpd webserver	2+	Add "listen" statement for each directly-monitored IPv6 address in httpd.conf (ie: Listen [2001:db8::1]:80)
BIND (named) name server	9+	Add listen-on-v6{any;}; to the options section of named.conf to listen for IPv6 connections. Add AAAA records for all publicly-accessible IPv6 sites in your domains.
MediaWiki	1.17+
Squid cache server	3.1.x	Add an "http_port" statement for each address (ie: http_port [2001:db8::2]:80 vhost defaultsite=example.org)
Varnish server	2.1+	Use the -a directive to list all addresses, IPv6 in square brackets (ie: -a 192.170.2.1:80,[2001:db8::2]:80)
MySQL	5.5.3+	Configuring the MySQL Server to Permit IPv6 Connections Note: On a MediaWiki site, the MySQL daemon is back-end software. There is no reason to invite the public to connect to it directly, so little or no reason to provide both IPv4 and IPv6 for it. The same is true of other back-end services (such as memcached).

Extensions

• CheckUser has complete support for IPv6 logging, though individual checks cannot exceed a /48 range (this is a changeable configuration setting in the latest revision).
• Before a certain revision, GlobalBlocking had support for IPv6 blocking if a schema change was manually applied to the GlobalBlocking database. After that revision, IPv6 support is complete.
• Extension:TrustedXFF hard-codes its list of trusted IPv6 proxies, instead of compiling them from trusted-hosts.txt; the list is a short one, but this is a kludge.

See also

• IPv6 support roadmap
• IPv6 keyword on bugzilla
• IPv6 deployment on Wikimedia