The blog post "A 'tinyurl' service for your domain" explains how to set up a ShortName service for your domain using Google Apps. For example, if your domain is example.com and you use Google Apps, you can configure it so that http://go.example.com is your enterprise's personal ShortName service.

NOTE: This is not about creating a "tinyurl" service for the world to use. This is for an enterprise.

It is useful to have a shortname service that only your users can use so that you can create links to internal pages. Rather than telling people a long difficult URL, you can say, "Today's lunch menu is at http://go.example.com/lunch". The blog post documents some of the benefits of empowering people to set up their own links. (Most important: they don't have to bother YOU to set up a new link!)

The Problem

The problem with the system is that the URL is still rather long. People would rather type "go/lunch" into their web browser and have it work. Sadly, Google Apps can't support this because of a technicality of how the HTTP protocol works. The "Host:" header in HTTP 1.1 lists the domain that the user typed into their web browser, not the FQDN. In other words, when Google Apps gets the HTTP request for "http://go/lunch" the webserver receives "go" as the hostname. Since Google Apps is providing this service for many domains, it can't tell if you want go.example.com or go.some-other-example.com.

As a result, users have to type "go.example.com/lunch" every time, which is much longer than "go/lunch".

The Solution

Google could solve this by using web cookies or some other scheme. None of which are particularly clean or easy. Until they do you can solve the problem by setting up a machine of your own that accepts requests as "go" and redirects them.

The server accepts HTTP requests for a site called "go" and redirect the request to go.example.com. You then create the right DNS records so that it works, and twiddle your DHCP configurations so that your laptops/workstations do the right thing.

The point of this Server Fault document is to explain the process then give configuration examples to help you do this for your site. Since I don't have access to or knowledge of every operating system in the world, I'm making this a "community wiki" so that people can fill in configuration snippets for as they get it working for them. I've put 'TODO' in area that particularly need improvement.

The Details

In this example we'll use "example.com" as the domain.

Step 1: Set up the Google Apps service the normal way.

Configure the service for go.example.com as normal. Test it and make sure a URL like http://go.example.com/foo works. Don't continue if this isn't complete. That would be like trying to repair your car before you own one.

Step 2: Select your redirector hostname

If your shortname service is go.example.com, ideally you'd make your redirector's name go.example.com. Sadly, physics prevents two bodies from being in the same place at the same time, and DNS obeys the laws of physics.

The trick is to have the redirector be the same hostname as the ShortName service, but in a different domain. For example, go.corp.example.com, go.ext.google.com, or go.this-is-different.example.com.

Large companies usually have an internal subdomain that is not exposed to the outside world. Usually internal hosts are INSIDEHOST.corp.google.com. That is where you put the redirector.

Some companies allocate a subdomain that is full of CNAMEs pointing to services that should be accessed from both inside and outside the company. That way there is one subdomain that needs to be put in people's DNS searchpath. (Unix people can think of this as having /usr/local/bin be a subdirectory full of symlinks) Traditionally this subdomain is ext.example.com. In that subdomain are CNAMEs like mail.ext.example.com, calendar.ext.example.com, vpn.ext.example.com, and so on.)

Warning: Adding yet another item to your DNS search path is yet another way to make your computers run slower. Doing an additional DNS query EVERY TIME is slow and surfing the web will be noticeably slower. It is much better to add this redirector to a subdomain that is already in your machine's DNS search path, even if this means adding a CNAME in multiple subdomains. For example, if your internal machines and machines connected to your VPN have corp.example.com in their search path already, add the CNAME there. If you want external machines not VPNed in to be able to access the redirector, it might be weird to hard code corp.example.com into their search path if that is the subdomain for machines never accessed from the outside. In that case, another CNAME can be added to an external subdomain (like ext.example.com) to point to the redirector. Update the web server configuration to support both.

For this example, let's assume you've selected that the redirector will be go.ext.example.com. The machine can be called anything you want, we'll do all the magic in DNS and the web server configuration.

Step 3: Planning for your redirector

The web server you are going to set up can be on an existing web server or a new one built just for this purpose. The key is that the machine has to be accessible from anywhere you want the ShortName service to work: inside the company, outside the company, when the user is connected via VPN. (You may choose to forego having this working from outside the company for security reasons. You may also, for security reasons, set up one machine on the inside and another on the outside.)

Note: You don't have to set up a new web server for this. You can add this to a pre-existing web server as long as the configuration doesn't exist.

Note: This can be rather complicated. You might want to focus on getting this working in the most simple case, then once working and tested, get it working for other situations. In particular, get it working in this order: 1. workstations/laptops inside the company 2. THEN machines connected by VPN, then machines outside the company (for example, at an Internet cafe). 3. THEN machines outside the network, without the VPN up 4. THEN test this for other operating systems

In this example, we'll assume there is a web server that is accessible at the same IP address whether you are inside or outside the company.

In our "go.corp.example.com" example, this means the "go" is in a subdomain that is only accessible to insiders, and requires a VPN to use the ShortName service. Since Google Apps is usually configured to work without a VPN (because all access is HTTPS), this is sub-optimal.

In our "go.ext.example.com" example, this means the subdomain is accessible from both inside and outside the company, and the A record points to an external IP address.

Step 4: Add DNS records for your redirector

Here are the DNS records required:

go.example.com.                IN CNAME ghs.google.com.
go.ext.example.com.            IN A 64.32.179.5
go-redirector.example.com  IN A 64.32.179.5

The first DNS record (go.example.com) should exist already as part of Step 1.

The second DNS record (go.ext.example.com) is an A record pointing at the IP address of the new web server you are configuring.

The third DNS record (go-redirector) is to help you when debugging.

Step 5: Configure the web server

Add the redirect to the web server. (This assumes the web server is already installed and running).

Here is the Apache configuration snippet:

<VirtualHost *:80>
        ServerName go-redirector.example.com
        ServerAlias go, go.ext, go.ext.example
        RewriteEngine on
        RewriteRule ^(.*)$ http://go.example.com$1 [R=permanent]
</VirtualHost>

How to test this. http://go-redirector.example.com should work at this point.

Do not proceed until this test works. Baby steps.

Step 6: Configure the client's DNS search path

Now we are going to configure machines (anything running a web browser) so that the DNS search path includes "ext.example.com"

On your DHCP server and VPN server send a DNS search path that is:

corp.example.com .

(the subdomain with the redirect host, followed by ".")

Alternatively you could use a search path like:

corp.example.com example.com .

However that is going to add an additional DNS lookup for EVERY darn web page we go to. Since they will fail 99% of the time, that's just going to make web surfing slow.

On workstations and laptops you need to make sure that the subdomain is included in their DNS search path. That way when the user types "go", the software will find it in the domain.

We want to configure the search path of the machine to include this subdomain every way that the search path can possibly be set:

Originally the DNS search path couldn't be set via DHCP. This is a newly added feature and not all DHCP clients support it. Even DHCP clients that do support it need to be modified because when a laptop is at (for example) an Internet cafe, it is talking to a DHCP server that you don't control. When a laptop uses a VPN, the VPN client software doesn't actually use DHCP but there is usually some way that the VPN server transmits the settings that one would usually get from a DHCP server.

Therefore you want to set the DNS search path in all these places:

• The DHCP server should send the DNS search path options
• Statically configured machines should have their DNS search path set
• Clients that use DHCP should be configured to pre-pend the corp.example.com domain to their search path if the DHCP server didn't include it already.

Below are instructions on how to do this on various DHCP servers and operating systems.

Configuring DHCP servers to include a DNS Search Path:

1. Windows DHCP instructions

TODO

2. ISC DHCP instructions

If the search path is just the domain that the machine should be in, then:

option domain-name "corp.example.com";

If the clients support RFC 3397 to supply a search path, then you can do this, but it's awkward as there's no native support for a data type which is a sequence of DNS hosts, each encoded as length-prefixed labels as in DNS. There's no way to write the values of an option defined as an array of records, where the record contains an array of another record, so you're down to using a data-string to encode things manually.

option dns-search-domains code 119 = string;
option dns-search-domains concat(
    encode-int(4,1), "corp", encode-int(7,1), "example", encode-int(3,1), "com", encode-int(0,1),
    encode-int(7,1), "example", encode-int(3,1), "com", encode-int(0,1)
    );

which should (untested) generate a two item search list.

3. dnsmasq DHCP instructions

TODO

Configuring statically configured machines:

1. Windows

TODO

2. Linux/Unix

Edit /etc/resolv.conf and make sure (1) the "domain corp.example.com" is the first line, (2) add/edit the "search" line to include the corp.example.com domain, (3) add an "options ndotes:2" line to reduce the load on your DNS servers.

domain corp.example.com
search corp.example.com exmaple.com
options ndots:2

Configuring DHCP clients to work when on other DHCP servers

TODO fill in for Windows, Linux, etc.

Step 7: Test, test, test!

Now users should be able to specify:

http://go/foo http://go.example/foo http://go.example.com/foo

In fact, as a confidence test, you'll want to test those URLs in all situations:

( each OS you support ) * ( internal LAN / at an Internet cafe / while on the VPN )

Step 8: Other advice

And lastly, one bit of advice: Even if you'd done a perfect job of this, you are still at risk of a http://go/foo link not working when a person tries to type it on a computer you didn't configure to force the DNS search path to include your domain. You should, therefore, publish links using the full URL: http://go.example.com/foo; and take the time to educate your company's PR department and others to always specify it that way.

Or at least encode them in HTML so that "go" is visible in the link text, but the actual HREF goes to the FQDN:

<a href="http://go.example.com/lunch">go/lunch</a>

Teaching people in the PR department to do this may be difficult. You might just want to tell them they have to use the long version (go.example.com) in anything they write because the short "go/lunch" only works by accident.

Step 8: HTTPS

TODO: Work out how to do with with HTTPS (the certifications are going to be very difficult, if not impossible, to get right).