rEZBA/0c15aff0352dmaster
/
README
This extension is used in the implementation of the Wikipedia Zero initiative: https://wikimediafoundation.org/wiki/Wikipedia_Zero
Wikipedia Zero is an ongoing partnership with various mobile carriers to make Wikipedia and sister projects available to users without data charges. In some cases this is limited to a special subdomain or a no-images configuration.
Fore more general and user-facing information, see the page linked above.
Technical overview
+---------------------+ | Mobile phone | connects to zero.wikipedia.org or m.wikipedia.org +---------------------+ | Carrier | routes traffic from known IP blocks +---------------------+ | | the interwebs | +---------------------+ | Varnish<->netmapper | Web proxy and netmapper detect carrier IP, add X-CS header +---------------------+ | App servers | LAMP stack! +---------------------+ | MediaWiki | PHP code... +---------------------+ | ZeroBanner | detects X-CS HTTP header, modifies HTML +---------------------+
The ZeroBanner extension to MediaWiki detects a carrier based on an "X-CS" and "X-Subdomain" HTTP header injected by our Varnish proxy servers. Th X-CS header is injected in Varnish with netmapper for performance.
Varnish configuration
Carrier detection by source IP block is done with netmapper by Varnish configuration. The configuration for Wikimedia servers can be found in Wikimedia's 'puppet' git repository, which holds most Wikimedia server configuration files as managed by the 'puppet' tool.
Visit the puppet.git repository and navigate to templates/varnish and start from mobile-frontend.inc.vcl.erb https://git.wikimedia.org/tree/operations%2Fpuppet.git
If you're curious about netmapper, see its repo.
https://gerrit.wikimedia.org/r/#/admin/projects/operations/software/varnish/libvmod-netmapper
An X-CS header with the carrier MCC/MNC code and an X-Analytics header key/value pair with the same value (eg X-Analytics: zero=502-13) are set. Additionally, the X-Subdomain header is set - an "mdot" subdomain is one such as en.m.wikipedia.org and a "zerodot" one ru.zero.wikipedia.org - the X-Subdomain value is either "M" or "ZERO".
ZeroBanner configuration
ZeroBanner normally enables itself only if the MediaWiki site configuration lists the site as 'wikipedia'; as of 23-December-2013, other Wikimedia sites do not have banners and URL rewriting turned on for the Wikipedia Zero program.
To test on your own vagrant instance, enable "zero" role:
$ vagrant enable-role zero $ vagrant provision
This extension uses the EventLogging extension for capturing the sent-once-per-cellular session X-MCCMNC header (in 2014 rebooted iOS and Android apps, for example) via an API hook. To support this EventLogging usage under MediaWiki Vagrant:
- Run the following: $ vagrant enable-role eventlogging $ vagrant provision
- Add the following lines to LocalSettings.php (or in Vagrant settings.d/<##>-<whatever>.php) $mwLogDir = DIR . '/../logs'; $wgDebugLogGroups['mccmnc'] = "$mwLogDir/mccmnc.log";
Testing
As noted above, on a local test wiki you will need to enable several settings.
You will want to manually add X-CS headers via browser addons such as:
- 'Modify Headers' add-on for Firefox
- 'ModHeaders' extension for Chrome
Be sure to set the following headers when testing against your local instance:
- X-CS (should match an article name in the Zero: namespace; e.g., "-TEST")
- X-Subdomain (set to "M" or "ZERO" to spoof whether you're on "mdot" or "zerodot")
You can change your User-Agent string via browser addons such as:
- 'Modify Headers' add-on for Firefox
- 'Default User Agent' add-on for Firefox
- 'ModHeaders' extension for Chrome
Set your User-Agent to a value like "android" so that mobile detection works.
Note that if testing in production, most custom headers will be overwritten by the Varnish server if you're coming from an IP block that's recognized for Wikipedia Zero -- this includes the Wikimedia San Francisco office. D'oh! This shouldn't happen with a local test server, though
Local Configuration Blobs
For people not interested in editing configurations, just use the API URL supplied above. But if you want to be able to edit configurations locally for testing purposes, you will need to create a Zero:-namespaced configuration entry to match the X-CS header that you add using 'Modify Headers'.
For example, go to http://127.0.0.1:8080/w/index.php?title=Zero:999-88&action=edit and populate the article with the data from https://meta.wikimedia.org/wiki/Zero:-TEST.
Testing specific modes
To test the landing page, go to /wiki/Special:ZeroRatedMobileAccess
To test the Main Page, go to /wiki/Main_Page