How to build a URL shortener with Apache

Create your own short links with Apache HTTP server's mod_rewrite feature.
233 readers like this.
Image of spider web

You as a Machine. Modified by Rikki Endsley. CC BY-SA 2.0.

Long ago, folks started sharing links on Twitter. The 140-character limit meant that URLs might consume most (or all) of a tweet, so people turned to URL shorteners. Eventually, Twitter added a built-in URL shortener (

Character count isn't as important now, but there are still other reasons to shorten links. For one, the shortening service may provide analytics—you can see how popular the links are that you share. It also simplifies making easy-to-remember URLs. For example, is much easier to remember than And URL shorteners can come in handy if you want to pre-share a link but don't know the final destination yet.

Like any technology, URL shorteners aren't all positive. By masking the ultimate destination, shortened links can be used to direct people to malicious or offensive content. But if you surf carefully, URL shorteners are a useful tool.

We covered shorteners previously on this site, but maybe you want to run something simple that's powered by a text file. In this article, we'll show how to use the Apache HTTP server's mod_rewrite feature to set up your own URL shortener. If you're not familiar with the Apache HTTP server, check out David Both's article on installing and configuring it.

Create a VirtualHost

In this tutorial, I'm assuming you bought a cool domain that you'll use exclusively for the URL shortener. For example, my website is, so I bought to use for my URL shortener (okay, it's not exactly short, but it feeds my vanity). If you won't run the shortener as a separate domain, skip to the next section.

The first step is to set up the VirtualHost that will be used for the URL shortener. For more information on VirtualHosts, see David Both's article. This setup requires just a few basic lines:

    <VirtualHost *:80>

Create the rewrites

This service uses HTTPD's rewrite engine to rewrite the URLs. If you created a VirtualHost in the section above, the configuration below goes into your VirtualHost section. Otherwise, it goes in the VirtualHost or main HTTPD configuration for your server.

    RewriteEngine on
    RewriteMap shortlinks txt:/data/web/shortlink/links.txt
    RewriteRule ^/(.+)$ ${shortlinks:$1} [R=temp,L]

The first line simply enables the rewrite engine. The second line builds a map of the short links from a text file. The path above is only an example; you will need to use a valid path on your system (make sure it's readable by the user account that runs HTTPD). The last line rewrites the URL. In this example, it takes any characters and looks them up in the rewrite map. You may want to have your rewrites use a particular string at the beginning. For example, if you wanted all your shortened links to be of the form "slX" (where X is a number), you would replace (.+) above with (sl\d+).

I used a temporary (HTTP 302) redirect here. This allows me to update the destination URL later. If you want the short link to always point to the same target, you can use a permanent (HTTP 301) redirect instead. Replace temp on line three with permanent.

Build your map

Edit the file you specified on the RewriteMap line of the configuration. The format is a space-separated key-value store. Put one link on each line:


Restart HTTPD

The last step is to restart the HTTPD process. This is done with systemctl restart httpd or similar (the command and daemon name may differ by distribution). Your link shortener is now up and running. When you're ready to edit your map, you don't need to restart the web server. All you have to do is save the file, and the web server will pick up the differences.

Future work

This example gives you a basic URL shortener. It can serve as a good starting point if you want to develop your own management interface as a learning project. Or you can just use it to share memorable links to forgettable URLs.

User profile image.
Ben Cotton is a meteorologist by training, but weather makes a great hobby. Ben works as the Fedora Program Manager at Red Hat. He is the author of Program Management for Open Source Projects. Find him on Twitter (@FunnelFiasco) or at

1 Comment

Great article. Thanks for sharing!

Creative Commons LicenseThis work is licensed under a Creative Commons Attribution-Share Alike 4.0 International License.