How to create a Symbolic Virtual Host Link for Apache 2.2


In this post I’ll explain how to create a Symbolic Virtual Host Link for Apache 2.2. This technique provides more flexibility in the local Virtual Host management. You will also avoid to set up every time a new Virtual Host for each application preventing, so, some of the most common and annoying server errors.

Let’s brush up on what a Virtual Host is by reading the following definition taken from the website

The term Virtual Host refers to the practice of running more than one web site (such as and on a single machine. Virtual hosts can be “IP-based“, meaning that you have a different IP address for every web site, or “name-based“, meaning that you have multiple names running on each IP address. The fact that they are running on the same physical server is not apparent to the end user.

I assume you already have

  • Apache installed and properly running on your local machine
  • A web application such as a WordPress blog, a Drupal CMS or a Symfony application in your Web Server Document Root

In this example my system has Apache v2.2.26 on a Mac but this article is not too different from any other tutorial written for another system not Unix based.
Also, here, the DocumentRoot has the following path /Users/MYUSER/Sites/.

At the end of the reading we’ll have a symbolic link on our Web Site root directory called “virtual”. By changing this link, we’ll be able to immediately change Virtual Host without touching the server configuration. This technique is really useful in case we want to test a website in a free local environment.
So, in a nutshell, by visiting http://virtual/ we’ll reach our application without writing all the document path like http://localhost/my-application-path.

Prerequisites: enable Apache Virtual Hosts

The first thing to do is to enable the virtual hosts in the Apache configuration. Today I’m using vim but any other editor is perfectly fine. From the Terminal, let’s write the following code

# edit as root user the Apache configuration file
sudo vim /etc/apache2/httpd.conf

# Search for "vhosts" and uncomment the following line
# by removing the dash # symbol on the left.
# Then save and close.
Include /private/etc/apache2/extra/httpd-vhosts.conf

To see if everything has been saved you can execute the following command

more /etc/apache2/httpd.conf | grep httpd-vhosts.conf

# and get the following result
Include /private/etc/apache2/extra/httpd-vhosts.conf

Now we just have enabled the Virtual Hosts for Apache.

Create a symbolic link

Lets’s do a summary to have clear where we are, what to do and what to expect.
We want to visit http://virtual/ and reach our web application that could be a WordPress Blog, a Drupal CMS or a custom Symfony application. The cool thing is that we can just visit our custom link and get our page.

Symbolic Virtual Host Link Schema (yEd - Graph Editor)

Symbolic Virtual Host Link Schema
(Graph created with yEd – Graph Editor)

As said, the http://virtual/ virtual host created will point to the “test” symbolic link and this, to the web application. In the next section we’ll set it up to return the application page we defined but now we have to create the symbolic link on our web server document root. From the terminal let’s execute the following

# move to the Document Root
cd /Users/MYUSER/Sites/

# create the symbolic link to my web application
ln -s my-web-application-folder/ test

# to double check if everything is fine, you can execute
ls -al
# and get
# test -> my-web-application-folder/

That’s it, quick and painless.

Put in place the new Virtual Host

The next step will be the configuration of a particular Virtual Host Name that we will call “virtual”. So, keep writing commands into the Terminal as follows

# edit the Apache Virtual Hosts configuration file
sudo vim /etc/apache2/extra/httpd-vhosts.conf

# append the following code to the bottom of the file
# and remember to change "MYUSER" in the
# Document Root directive. Then save and close.
# (we'll ignore the many directives we could set up here
# and just focus on our virtual host)
<VirtualHost *:80>
    ServerName virtual

    DocumentRoot "/Users/MYUSER/Sites/test"
    <Directory "/Users/MYUSER/Sites/test">
        AllowOverride All

        Require all granted

    ErrorLog /var/log/apache2/project_error.log
    CustomLog /var/log/apache2/project_access.log combined

We are almost there! Add the new host created to the hosts file of our local machine to let it know we have a special local instruction in case we digit http://virtual/. Depending on the machine, the hosts file is located in a different directory. For more information you can visit the Rackspace article How do I modify my hosts file.
Now, write as follows

# edit the hosts file (I'm on Mac now)
sudo vim /etc/hosts

# append to the bottom of the file.
# Then save and close.       virtual

We just need now to restart Apache to make all the changes effective.

sudo apachectl graceful

In case of problems, try to test the Apache configuration with the following command to check the Apache config file syntax

apachectl -t

That’s it! Great Job!
Now, by visiting http://virtual/ (feel free to click on this link 🙂 ) you’ll see your web application home page.
If you want to quickly change application pointed by http://virtual/, just replace the test symbolic link on the Server Document Root as follows

# move to the Document Root
cd /Users/MYUSER/Sites/

# remove the current symbolic link
rm test

# create a new symbolic link
# to a different application
ln -s another-application/ test

In this way, without touching any more the Apache config file, we are now able to “change the pointer” of our Virtual Host with a Symbolic Virtual Host Link.