Installing and configuring the Apache 2.2.x web server on FreeBSD

Installing the port

Apache 2.2 can be installed from the ports with the following commands

# cd /usr/ports/www/apache22
# make install

You will need to add an enable line for Apache to your /etc/rc.conf file

apache22_enable="YES"

Apache installs a start up script in /usr/local/etc/rc.d, but to stop and start the port the apachectl command is used which we will be looking at later when it is time to start the server.

Configuring Apache's httpd.conf

The httpd.conf contains most all of the important configuration settings. Everything can be done here from adding virtual hosts, to setting the log files, to setting .htm files to be parsed for php. You can open the httpd.conf file for editting with

ee /usr/local/etc/apache22/httpd.conf

When first getting the web server going you will be editting this file a lot, so its not a bad idea to create an alias for the above command in your shell.

The first thing you will need to change in the file to get your server going is the ServerName to the hostname you want to use for the server. If you do not have one you can use the IP address, or localhost. This will need to be followed by the port number.

ServerName www.yourdomain.com:80

Currently in Apache 2.2.x the default directory is /usr/local/www/apache22 instead of the old default. This should be changed to the standard directory of /usr/local/www/data in every spot. You can move the folder like this if you do not have a previous version of apache installed that has created the directory already.

# mv /usr/local/www/apache22 /usr/local/www/

You can replace it easily with sarep from the ports with this command.

# sarep "/usr/local/www/apache22" "/usr/local/www" httpd.conf

This is enough to get the server going so that you can check that it will run, so do that now.

Loading the accf_http module

On FreeBSD you must load the accf_module before you can start apache, otherwise you are sure to get an httpready error. To load the module use kldload

# kldload accf_http

If it loaded successfully then it will not give any errors or output. To have it load on boot add this to your /boot/loader.conf file

accf_http_load="YES"

Starting Apache

Apache is controlled with apachectl, some examples of its usage are

# apachectl start
# apachectl restart
# apachectl graceful
# apachectl stop

The graceful option has the same result as restart, it just does it in a nice way as opposed to restart forcefully restarting the server.

Before restarting or starting Apache it is best to run the configtest to check for errors in the httpd.conf

# apachectl configtest

If this comes back OK then you are good to go. When starting Apache it will not tell you if the start was successful, the easiest way to check this is to restart it. If apache failed to start up previously it will tell you that Apache is not running when you perform the restart.

If Apache will not start you can check the logs for error messages

# tail /var/log/messages
# tail /var/log/httpd-error.log

To check if you can get to the server just point your web browser to the machine and you should get a message telling you that Apache has been successfully installed.

Adding Virtual Hosts

Virtual hosts can be set up in Apache to direct traffic depending on the hostname they used to access the server. This lets you have many domain names, with only one ip address. To add virtual hosts open the /usr/local/etc/apache22/httpd.conf file and unhash the virtual host include so that is brings in the settings for vhosts.

# Virtual hosts
Include etc/apache22/extra/httpd-vhosts.conf

Then add the virtual hosts which declare the virtual host to watch for, the directory of the web site, and where the logs go. They can be added to either httpd.conf or a new .conf file in /usr/local/etc/apache22/Includes All files in /Includes ending with .conf will be included in the httpd.conf the same as if you had put the code directly into that file.

<VirtualHost *:80>
DocumentRoot /usr/local/www/yourdomain
ServerAdmin root@yourdomain.com
ServerName www.yourdomain.com
ServerAlias stuff.yourdomain.com
CustomLog /usr/local/www/logs/domain-access_log combined
ErrorLog /usr/local/www/logs/domain-error_log
</VirtualHost>

In the above example, when a user goes to www.yourdomain.com or stuff.yourdomain.com, Apache will see the virtual host directive for it and serve them pages from /usr/local/www/yourdomain

The access log uses the combined format which logs all the information, such as the browser, refer, and page. The logs can be set to any file. If you do use this place or another for logging make sure that the directory exists or Apache will not start. We will be working with these logs later with Awstats and also for real-time monitoring

More Virtual Hosts can be added by simply creating more virtual host directives in the httpd.conf file. The first virtual host listed will be the default for it you access the server by its IP. To change this back to pointing at /usr/local/www/data you will need to make a virtual host directive pointing to that directory and place it before any others.

Accessing Virtual Hosting without the Hostname

Since virtual hosts work strictly by the hostname they are not usable when you are behind a firewall or router and the machines behind it have local ips such as 192.168.0. Everytime you try to access the virtual host you will simply be taken to the router and given an error. To fix this we will need to open up more ports for Apache to listen on so that we can access the sites directly through these instead of virtual hosts. Since the machine is behind the firewall and getting ports getting a limited number of ports forwarded to it these will not be accessible to the outside world unless you have them forwarded to it.

Apache specifies which ports it listens on with the LISTEN lines in the httpd.conf file. The default is to only listen on 80, but we need it to listen on extra ports so more LISTEN lines need to be added. If we had 3 virtual hosts that we wanted to access by ports 6000, 6001, and 6002 the httpd.conf file would look like this

Listen 80
Listen 443
Listen 6000
Listen 6001
Listen 6002

Next we need to set up virtual hosts for these so Apache knows what directory to serve from when you it is accessed on these new ports. They are similiar to the virtual hosts set up above, only most of the settings can be left off

<VirtualHost *:6000>
DocumentRoot /usr/local/www/yourdomain
ServerName 192.168.0.45
</VirtualHost>

In this example anything coming in on port 6000 points to the /usr/local/www/yourdomain directory, which is the same as the Virtual Host we set up above, but now we can access it by going to http://192.168.0.45:6000 instead of http://www.yourdomain.com/ The 192.168.0.45 should be changed to whatever the local ip of your web server is.

There are no log files specified here since this should only be accessed by yourself testing the site locally, and you wouldn't want to count this in the web site statistics.

A virtual host like this should also be created for the other two sites at 6001, and 6002 simply changing the port and DocumentRoot for each virtual host directive.

Turning on the defaults

Many of the default settings are now included in a seperate file and turned off default. To use them unhash this part of your httpd.conf file.

# Various default settings
Include etc/apache22/extra/httpd-default.conf

Common Errors

The most common error when setting up Apache is the "cannot determine local host name" error. This error is caused by the hostname resolving to a different IP than the one it has. To check what your current hostname is use hostname. Then use nslookup on the hostname to get the IP and compare it to the IP that your machine is actually using with ifconfig. For example:

# hostname
	server.mydomain.com

# nslookup server.mydomain.com
	Non-authoritative answer:
	Name:   server.mydomain.com
	Address: 10.1.1.30

# ifconfig
	inet 192.168.0.5 netmask 0xffffff00

We can see here that the IP of the hostname does not match the real IP of the machine. A quick fix for this is to just add the hostname to your /etc/hosts file.

# ee /etc/hosts
	
	192.168.0.5	server.mydomain.com.

This will set the hostname to the IP assigned to your machine. Make sure you do not forget to put a . on the end when adding this line!

Another very common error is this one

[warn] (2)No such file or directory: Failed to enable 
the 'httpready' Accept Filter

It is caused by not having the accf_http kernel module loaded. Loading it is explained above.

Password Protecting Directories

Directories are set to password protected in the the httpd.conf file also. See the tutorial on password protecting directories with htaccess in Apache

Encrypting Traffic with SSL

The data moving between the user and your server well be plain text unless you use encrypt it. See the tutorial on setting up SSL with Apache 2.

Apache 2.0

Go here for the old Apache 2.0 tutorial.

Comments