29.8. Apache HTTP Server

Contributed by Murray Stokely.

29.8.1. Overview

FreeBSD is used to run some of the busiest web sites in the world. The majority of web servers on the Internet are using the Apache HTTP Server. Apache software packages should be included on the FreeBSD installation media. If Apache was not installed while installing FreeBSD, then it can be installed from the www/apache22 port.

Once Apache has been installed successfully, it must be configured.


This section covers version 2.2.X of the Apache HTTP Server as that is the most widely used version for FreeBSD. For more detailed information beyond the scope of this document about Apache 2.X, please see http://httpd.apache.org/.

29.8.2. Configuration

The main Apache HTTP Server configuration file is installed as /usr/local/etc/apache22/httpd.conf on FreeBSD. This file is a typical UNIX® text configuration file with comment lines beginning with the # character. A comprehensive description of all possible configuration options is outside the scope of this book, so only the most frequently modified directives will be described here.

ServerRoot "/usr/local"

This specifies the default directory hierarchy for the Apache installation. Binaries are stored in the bin and sbin subdirectories of the server root, and configuration files are stored in etc/apache.

ServerAdmin you@your.address

The address to which problems with the server should be emailed. This address also appears on some server-generated pages, such as error documents.

ServerName www.example.com

ServerName allows an administrator to set a host name which is sent back to clients for the server. This is useful if the host is different than the one that it is configured with (i.e., use www instead of the host's real name).

DocumentRoot "/usr/local/www/apache22/data"

DocumentRoot: The directory where documents will be served from. By default, all requests are taken from this directory, but symbolic links and aliases may be used to point to other locations.

It is always a good idea to make backup copies of the Apache configuration file before making changes. When the configuration of Apache, is complete, save the file and verify the configuration using apachectl(8). To do this, issue apachectl configtest which should return Syntax OK.

29.8.3. Running Apache

The www/apache22 port installs an rc(8) script to aid in starting, stopping, and restarting Apache, which can be found in /usr/local/etc/rc.d/.

To launch Apache at system startup, add the following line to /etc/rc.conf:


If Apache should be started with non-default options, the following line may be added to /etc/rc.conf:


The Apache configuration can be tested for errors after making subsequent configuration changes while httpd is running. This can be done by the rc(8) script directly, or by the service(8) utility by issuing one of the following commands:

# service apache22 configtest


It is important to note that the configtest is not an rc(8) standard, and should not be expected to work for all rc(8) startup scripts.

If Apache does not report configuration errors, the Apache httpd can be started with service(8):

# service apache22 start

The httpd service can be tested by entering http://localhost in a web browser, replacing localhost with the fully-qualified domain name of the machine running httpd, if it is not the local machine. The default web page that is displayed is /usr/local/www/apache22/data/index.html.

29.8.4. Virtual Hosting

Apache supports two different types of Virtual Hosting. The first method is Name-based Virtual Hosting. Name-based virtual hosting uses the clients HTTP/1.1 headers to figure out the hostname. This allows many different domains to share the same IP address.

To setup Apache to use Name-based Virtual Hosting add an entry like the following to httpd.conf:

NameVirtualHost *

If the webserver was named www.domain.tld and a virtual domain for www.someotherdomain.tld then add the following entries to httpd.conf:

<VirtualHost *> ServerName www.domain.tld DocumentRoot /www/domain.tld </VirtualHost> <VirtualHost *> ServerName www.someotherdomain.tld DocumentRoot /www/someotherdomain.tld </VirtualHost>

Replace the addresses with the addresses needed and the path to the documents with what are being used.

For more information about setting up virtual hosts, please consult the official Apache documentation at: http://httpd.apache.org/docs/vhosts/.

29.8.5. Apache Modules

There are many different Apache modules available to add functionality to the basic server. The FreeBSD Ports Collection provides an easy way to install Apache together with some of the more popular add-on modules. mod_ssl

The mod_ssl module uses the OpenSSL library to provide strong cryptography via the Secure Sockets Layer (SSL v2/v3) and Transport Layer Security (TLS v1) protocols. This module provides everything necessary to request a signed certificate from a trusted certificate signing authority to run a secure web server on FreeBSD.

The mod_ssl module is built by default, but can be enabled by specifying -DWITH_SSL at compile time. Language Bindings

There are Apache modules for most major scripting languages. These modules typically make it possible to write Apache modules entirely in a scripting language. They are also often used as a persistent interpreter embedded into the server that avoids the overhead of starting an external interpreter and the startup-time penalty for dynamic websites, as described in the next section.

29.8.6. Dynamic Websites

In the last decade, more businesses have turned to the Internet in order to enhance their revenue and increase exposure. This has also increased the need for interactive web content. While some companies, such as Microsoft®, have introduced solutions into their proprietary products, the open source community answered the call. Modern options for dynamic web content include Django, Ruby on Rails, mod_perl2, and mod_php. Django

Django is a BSD licensed framework designed to allow developers to write high performance, elegant web applications quickly. It provides an object-relational mapper so that data types are developed as Python objects, and a rich dynamic database-access API is provided for those objects without the developer ever having to write SQL. It also provides an extensible template system so that the logic of the application is separated from the HTML presentation.

Django depends on mod_python, Apache, and an SQL database engine. The FreeBSD Port will install all of these pre-requisites with the appropriate flags.

Example 29.3. Installing Django with Apache2, mod_python3, and PostgreSQL
# cd /usr/ports/www/py-django; make all install clean -DWITH_MOD_PYTHON3 -DWITH_POSTGRESQL

Once Django and these pre-requisites are installed, the application will need a Django project directory along with the Apache configuration to use the embedded Python interpreter. This will be the interpreter to call the application for specific URLs on the site.

Example 29.4. Apache Configuration for Django/mod_python

A line must be added to the apache httpd.conf file to configure Apache to pass requests for certain URLs to the web application:

<Location "/"> SetHandler python-program PythonPath "['/dir/to/the/django/packages/'] + sys.path" PythonHandler django.core.handlers.modpython SetEnv DJANGO_SETTINGS_MODULE mysite.settings PythonAutoReload On PythonDebug On </Location> Ruby on Rails

Ruby on Rails is another open source web framework that provides a full development stack and is optimized to make web developers more productive and capable of writing powerful applications quickly. It can be installed easily from the ports system.

# cd /usr/ports/www/rubygem-rails; make all install clean mod_perl2

The Apache/Perl integration project brings together the full power of the Perl programming language and the Apache HTTP Server. With the mod_perl2 module it is possible to write Apache modules entirely in Perl. In addition, the persistent interpreter embedded in the server avoids the overhead of starting an external interpreter and the penalty of Perl start-up time.

mod_perl2 is available in the www/mod_perl2 port. mod_php

Written by Tom Rhodes.

PHP, also known as PHP: Hypertext Preprocessor is a general-purpose scripting language that is especially suited for Web development. Capable of being embedded into HTML its syntax draws upon C, Java™, and Perl with the intention of allowing web developers to write dynamically generated webpages quickly.

To gain support for PHP5 for the Apache web server, begin by installing the lang/php5 port.

If the lang/php5 port is being installed for the first time, available OPTIONS will be displayed automatically. If a menu is not displayed, i.e., because the lang/php5 port has been installed some time in the past, it is always possible to bring the options dialog up again by running:

# make config

in the port directory.

In the options dialog, check the APACHE option to build mod_php5 as a loadable module for the Apache web server.


A lot of sites are still using PHP4 for various reasons (i.e., compatibility issues or already deployed web applications). If the mod_php4 is needed instead of mod_php5, then please use the lang/php4 port. The lang/php4 port supports many of the configuration and build-time options of the lang/php5 port.

This will install and configure the modules required to support dynamic PHP applications. Check to ensure the following sections have been added to /usr/local/etc/apache22/httpd.conf:

LoadModule php5_module libexec/apache/libphp5.so
AddModule mod_php5.c <IfModule mod_php5.c> DirectoryIndex index.php index.html </IfModule> <IfModule mod_php5.c> AddType application/x-httpd-php .php AddType application/x-httpd-php-source .phps </IfModule>

Once completed, a simple call to the apachectl command for a graceful restart is needed to load the PHP module:

# apachectl graceful

For future upgrades of PHP, the make config command will not be required; the selected OPTIONS are saved automatically by the FreeBSD Ports framework.

The PHP support in FreeBSD is extremely modular so the base install is very limited. It is very easy to add support using the lang/php5-extensions port. This port provides a menu driven interface to PHP extension installation. Alternatively, individual extensions can be installed using the appropriate port.

For instance, to add support for the MySQL database server to PHP5, simply install the port databases/php5-mysql.

After installing an extension, the Apache server must be reloaded to pick up the new configuration changes:

# apachectl graceful

All FreeBSD documents are available for download at http://ftp.FreeBSD.org/pub/FreeBSD/doc/

Questions that are not answered by the documentation may be sent to <freebsd-questions@FreeBSD.org>.

Send questions about this document to <freebsd-doc@FreeBSD.org>.