| layout | title | cover | date | organiser |
|---|---|---|---|---|
post |
DNS - cname Set Up |
img/blur-background-1680x1050-spectrum-electromagnetic-4k-901-1.jpg |
2015-03-03 |
Lucas Gatsas |
Step 1: Add a new file CNAME to your GitHub Pages repository containing only one line: your top-level domain name.
E.g.:
example.com Step 2: [Optional] but highly recommended
2.1: Remove all other top-level records (prefixed with @) of type A from your DNS configuration.
2.2: Remove a CNAME record for the second-level domain www if it is present.
Step 3: Add these 3 entries to the very top of your DNS configuration:
@ A 192.30.252.153 @ A 192.30.252.154 www CNAME your_github_username.github.io. Replace your_github_username with your actual GitHub username.
Step 4: Wait for your DNS changes to propagate.
DNS changes aren't effective immediately. They can take up to a full day to propagate.
Long answer This issue has two sides. One is the DNS configuration itself. Another one is the way GitHub Pages forwards HTTP requests.
We need to know a few things to understand what GitHub is trying to say in their documentation.
DNS Entry Types There are two types of DNS records which interest us: CNAME and A.
A is also known as Apex or sometimes as root entry. It forwards requests to a specified fixed IP address. CNAME entry forwards requests to a specified URL (actual valid plain text URL, not an IP address).
DNS Load balancing GitHub has one central URL address which accepts all DNS requests for GitHub Pages: http://username.github.io. That URL is resolved to different IP addresses based on your geographical location. Website hosted on GitHub Pages is a simple collection of HTML, CSS and JS files. GitHub distributes these files to different servers across the globe. So that when your browser sends a request from Europe it receives data from a server in Europe. The same is valid for the requests from Asia and the USA.
What GitHub is trying to say Since A records in DNS must contain IP addresses, and they must be either 192.30.252.153 or 192.30.252.154, there is no way to forward requests to a server located somewhere in Europe or Asia. Your website hosted at GitHub Pages will be downloaded from a central GitHub Pages server. There is a minor risk that if both GitHub Pages DNS servers (x.x.x.153 and x.x.x.154) will be down for some reason, all custom domains which use fixed GitHub Pages IP addresses will not be accessible (their DNS requests will not be resolvable).
That is why GitHub strongly suggests to either use a second-level domain for your GitHub Pages (e.g. blog.example.com) or use a DNS service provider that supports a record type ALIAS that acts as A record but forwards request to a URL address (e.g. username.github.io) instead of a fixed IP address.
How GitHub Pages treats HTTP requests After a DNS request for your_github_username.github.io. is resolved into an IP address, e.g. 192.30.252.153 your browser sends an HTTP request to that server with an HTTP header Host. Below are curl examples that load the same website (these examples might not work if you are behind a proxy server):
$> curl --header "Host: your_github_username.github.io" http://192.30.252.153/ $> curl --header "Host: www.example.com" http://192.30.252.153/ $> curl --header "Host: example.com" http://192.30.252.153/
This way GitHub Pages servers know which user website to serve.
GitHub Pages server will automatically redirect HTTP request to the top-level domain if your CNAME file contains example.com but www.example.com is requested.
The same is valid if your CNAME file contains www.example.com but the header Host in the HTTP request contains example.com. Why can't I add a CNAME record entry that accepts a top-level request (@) to my DNS configuration? Quote from the GitHub Pages documentation:
Warning: Do not create a CNAME record for your custom apex domain! Doing so may cause issues with other services, such as email, on that domain.
Some DNS Checks via. Commandlines
Space-Odysseys-Mac-Pro:~ cyberspace$ dig blog.lucasgatsas.ch ; <<>> DiG 9.8.3-P1 <<>> blog.lucasgatsas.ch ;; global options: +cmd ;; Got answer: ;; ->>HEADER<<- opcode: QUERY, status: NOERROR, id: 1357 ;; flags: qr rd ra; QUERY: 1, ANSWER: 1, AUTHORITY: 0, ADDITIONAL: 0 ;; QUESTION SECTION: ;blog.lucasgatsas.ch. IN A ;; ANSWER SECTION: blog.lucasgatsas.ch. 9458 IN A 104.219.248.121 ;; Query time: 44 msec ;; SERVER: 10.0.0.1#53(10.0.0.1) ;; WHEN: Sun Feb 28 23:32:09 2016 ;; MSG SIZE rcvd: 53 Space-Odysseys-Mac-Pro:~ cyberspace$ dig spaceg.github.io ; <<>> DiG 9.8.3-P1 <<>> spaceg.github.io ;; global options: +cmd ;; Got answer: ;; ->>HEADER<<- opcode: QUERY, status: NOERROR, id: 54684 ;; flags: qr rd ra; QUERY: 1, ANSWER: 2, AUTHORITY: 0, ADDITIONAL: 0 ;; QUESTION SECTION: ;spaceg.github.io. IN A ;; ANSWER SECTION: spaceg.github.io. 3600 IN CNAME github.map.fastly.net. github.map.fastly.net. 30 IN A 185.31.17.133 ;; Query time: 42 msec ;; SERVER: 10.0.0.1#53(10.0.0.1) ;; WHEN: Sun Feb 28 23:32:24 2016 ;; MSG SIZE rcvd: 85
Flush DNS Most operating systems and DNS clients will automatically cache IP addresses and other DNS results, this is done in order to speed up subsequent requests to the same hostname. Sometimes bad results will be cached and therefore need to be cleared from the cache in order for you to communicate with the host correctly. All major operating systems allow you to force this process. Outlined below are the common steps you will need to follow in order to flush your DNS cache.
Clear your Flushing Cache:
Apple OS X Flushing the DNS in Mac OS X is an easy process, but the steps taken will depend on which version of OS X you are running.
Mac OS X El Capitan If you are running Mac OS X 10.11, you need to follow the below steps:
Open up the command terminal. Run the command sudo killall -HUP mDNSResponder
Mac OS X Yosemite If you are running Mac OS X 10.10, you need to follow the below steps:
Open up the command terminal. Run the command sudo discoveryutil udnsflushcaches
$sudo killall -HUP mDNSResponder
Other Operating Systems - Linux
Linux If you are running the nscd Name Service Cache Daemon and wish to flush your DNS cache, then you will need to do the following.
Open up a command terminal (either as root or run step 2 with sudo).
Run the command /etc/init.d/nscd restart
Link: Transport Layer Protocols Link: Application Layer Protocols Link: Link Protocols Link: internet Layer Protocols Link: Domian Name Systems