Install

Jason Fesler edited this page Feb 21, 2015 · 7 revisions

Installation Outline

Caution: This is not the simplest of apps to install. This is not just a simple pgkadd, a yum install, or a clicky-clicky-instally-thingee. You'll need to have at least mid-level System Administration or Dev Ops skills.

You'll also need:

  • root
  • firewall access
  • one IPv4 address, two IPv6 addresses.
  • dns server access
  • ability to install new dns servers
  • not be afraid of perl, php
  • not afraid of identifying missing depencies for your OS
  • a bit of patience

If you want to help make this documentation better, ask jfesler for r/w access to update the wiki.

Prep work

Identify the host you'll run the mirror on.

While it is possible to run this on a shared web server, it is usually going to be easier to run it on at least a dedicated Virtual Machine (VM). You'll need to not only new virtual hosts, but you'll need to be able to run a custom Apache module; and possibly even a DNS server on the same host. You'll also need to run a custom daemon and run modified ip6tables firewall rules.

Make sure you have root level acess.

Most parts of this require root. In particular, web server configuration, DNS server install and configuration, firewall configuration, and such.

Make sure you have Native IPv6

Make sure that the host or VM you plan on using has native IPv6. Specifically, this should not be tunneled from TunnelBroker or from Sixxs. It should be native, and able to support a full MTU of 1500.

Make sure that you can successfully run these commands:

  • curl http://ipv6.test-ipv6.com/ip/
  • curl http://ipv6.test-ipv6.com/ip/\?size=1600

Identify a domain name to use

This can be a dedicated domain; or a sub-domain off of your existing domain. Public mirrors are encouraged to follow the naming formats seen at http://test-ipv6.com/mirrors.html .

Review the download options

DownloadOptions outlines multiple ways to download what you need to operate a mirror. rsync is strongly preferred; and examples on all pages will reflect that.

Installation steps

Install DNS

InstallDNS outlines the DNS zone files you'll need on your existing DNS servers. It also identifies DNS zone files that will need to be placed on a new DNS server; possibly running on the same host as your web server.

Install Apache and PHP

InstallApachePHP outlines the Apache and PHP requirements.

Install the mod_ip Apache Module

InstallModIP describes how to get the mod_ip apache module source code; to compile it; and to install it. This is a standalone project, hence the separate download.

Install the Content

InstallContent outlines downloading and installing the HTML, JavaScript, CSS, and PHP needed to host the site; and also outlines a method of keeping this content automatically up to date.

Configure Apache

InstallApacheVirtualHost shows a couple of ways to configure Apache; depending on whether you are using a dedicated VM, or sharing web hosting with other web sites.

Configure the mirror

InstallProjectConfigFile documents what changes you need to make to the site's /site/config.js and /site/private.js files. These will be used to tell the JavaScript application where your mirror is, what IP addresses it has, the mirror operator's contact details, and possibly even the operator's company logo.

Install and configure PMTUD testing feature

InstallPMTUD documents a new daemon to be installed; along with firewall changes and config changes to /site/config.js. This feature will give better indication to clients with broken Path MTU Detection, by emulating a path with a smaller MTU of just 1280 bytes (IPV6 legal minimum). This feature is expected to become a requirement for new mirrors. As most mirrors get updated, the documentation on this site will be streamlined to favor the new install vs updating the existing install.

Configure charts (optional).

[InstallCharts]] -- If you don't mind a few extra requirements, and you are not afraid of MySQL, then consider enabling the charting features. This will cause every visit to your mirror to store test results in your database; and to generate a graph daily. This may be useful for your boss to justify working on the project. That said, most mirrors are low value; and the charts are pretty dull.

Even though I mention that most mirrors are low volume, I'll point out that they are still valuable. Nearby mirrors help people get accurate readings. And the quantity of mirrors help each user test IPv6 to many sites globally, highlighting any network peering issues.

Stay Current

It is vitally important that mirrors stay up to date. You can do this via automation; the setup instructions in InstallContent recommend you set up a cron job.

It is also very important that when you configured the site (InstallProjectConfigFile) that you put in an accurate contact address; even if you don't permit comments. I use this to notify mirrors of any major issues.

Validation

Your final steps should be to ensure that everything works. There is an online validator that can help, if your mirror is publicly reachable. Learn more at Validation.

Last, please subscribe to the MailingList.

Contributing to the Community

Making your mirror official

Adding your mirror to the official mirrors list is quite valuable to the community. Not only do you offer a nearby mirror that will help them get an accurate test; you're also making your hosted images useful for a global test from people visiting any mirror in the world. This global test is useful for finding IPv6 Internet issues between service providers. If you're willing, please see Validation and BecomeAnOfficialMirror.

Translations

Updating translations allows people in your country to use and understand the test, without having a prerequisite knowledge of English. Even better: any contributions you make will be applied to all mirrors globally.

Note: If you decide against operating a mirror, but you can still offer translations, your help is still very much welcome.

See the LocalizationPlan for more details.

Developers

See Developer Notes if you want to review the source code, make changes, commit to the project, or otherwise adapt the project to your organization's needs.