Linux Home Server HOWTO
Home Next

Chapter 13 - Apache Web Server

Version: - httpd 2.2.0
- squirrelmail 1.4.6

Basic Configuration
Starting the Server
Creating a Favicon
User Directories
Enabling CGI Scripts
Authenticating Users
Virtual Hosts
Using SSL Certificates
Webmail Configuration

The Apache web server is a highly scalable product capable of running on many platforms and serving thousands of pages a minute. It provides a stable and secure environment for the host server, and is the industry leader in the web server market. The server package comes bundled with most Linux distributions and only requires little configuration changes (if any) to be up and serving pages immediately. If you're serious about your web development and its a fully dynamic hosting environment you need, then Apache, PHP and MySQL are perfectly suited together, and are also provided with most distributions.

The Apache server configuration can be a little scary because its a large file containing three main sections (Global Environment, Main Server Configuration and Virtual Hosts). In fact, the configuration has been broken even further so that any additional modules have their own configuration files, which are located in a different directory. Confused? Don't be, its relatively easy to understand once you start playing with it.

Configuration File Dir:
Extra Module Files Dir:

This chapter will cover some of the more common configuration details so you can get the Apache server running and also provide you with some more advanced steps to enable user directories, authentication, and SSL so you can tailor the server to your needs. The Apache web server comes complete with its own user manual detailing many configuration scenarios, FAQs and even HOWTOs. To access the manuals (once your server is running) goto http://localhost/manual.

Basic Configuration

The initial configuration file for Apache already provides enough details to get the server running straight away and if you only want the basics in hosting, it will probably be all you need. But like most individuals, we want to tailor it to suit our needs. Before we start, lets backup the original configuration so we have a good file to restore from if everything turns bad. If you are not one hundred percent sure what a particular configuration directive does, then its advised not to change it.

[bash]# cp /etc/httpd/conf/httpd.conf /etc/httpd/conf/httpd.conf.original
[bash]# vi /etc/httpd/conf/httpd.conf

The ServerRoot directive is where the configuration files, error logs, and access files are stored (normally the log and error directories are symbolic links to another location), you probably don't want to change this setting.

ServerRoot "/etc/httpd"

Warning !! DO NOT add a trailing slash "/" to the directory names when making changes. If they are already there (like cgi-bin), then leave them.

The Listen directive specifies the port number and IP address (optional) that the server should bind and listen to.

Listen 80 All clients can connect (preferred)
Only clients on the internal network can connect

The Apache server has many modules that have been written to support certain events, like allowing users to have their own websites running from the main server. These modules must be declared and loaded inside the configuration file before the functions required from the module can be used.

Not having a particular module loaded when you need it can be quite frustrating when you are debugging your server, always have a quick look at the Module Index in the manual for further details and assistance (http://localhost/manual/mod).

LoadModule userdir_module modules/
LoadModule cgi_module modules/
LoadModule rewrite_module modules/
These are examples, of LoadModule - do not adjust unless needed.

This Include statement allows any separate configuration files in the "/etc/httpd/conf.d" directory, to be loaded with the main configuration during start/reload time. The separate configuration files must end in the .conf file extension.

Include conf.d/*.conf

The server provides some basic real-time status information while its operating, some further details can be provided by setting the ExtendedStatus to "on".

ExtendedStatus On

The User and Group values specify the local user and group accounts that Apache should run as.

User apache
Group apache

This directive provides a contact email address for any error messages that a user might receive from the server.

ServerAdmin [email protected]

Remember that our real server's hostname is, but people out on the Internet are accessing our server with the URL of because we have set up an alias (CNAME) in the DNS. Setting the ServerName directive allows the server to handle redirections easier. The ServerName is also displayed in any error messages that a user might receive from the server.

If you set the ServerName directive, you should also set the UseCanonicalName directive to "On" (recommended for both).

UseCanonicalName On

Note !! For DNS, the servers real name is galaxy, the www name is an alias (CNAME) which points to the real galaxy hostname.

The DocumentRoot is where all of your new web pages need to be placed so Apache can serve them to connecting users.

DocumentRoot "/var/www/html"

The DirectoryIndex details the name of the default page which is displayed when someone connects to the server. The default page is checked in sequential order as they are listed, so index.html would be served before index.html.var if they both existed in the same directory.

If you have extra modules loaded like PHP, they may have their own DirectoryIndex directives within their own configuration files (in conf.d directory). Always check the other configurations before adding your own, you may find its unnecessary.

DirectoryIndex index.html index.html.var

The AccessFileName specifies the first file read each time a user enters a directory. The filename (normally .htaccess) can contain extra configuration settings that are applied to the directory where it resides. The .htaccess file is commonly used to specify any access restrictions or user authentication details for the directory (see Authenticating Users).

AccessFileName .htaccess

Caution !! It is widely known that Apache uses the filename ".htaccess" as the default file for basic authentication. It is recommended that you change the name of the file as any serious attacker will definitely target that filename. The file should be safe, but the extra precaution won't hurt. Keep with ".ht" for start of filename.

Setting HostnameLookups tells the server to do a reverse DNS lookup for every IP address that connects to it, then the resulting hostname is logged in the access log. Unless you are doing detailed log file analysis, you shouldn't need this feature.

HostnameLookups Off

Any error messages generated by the server can have an additional footer added with contains information about the server. The "Email" value configures the footer informatiion to contain the "ServerAdmin" email address.

ServerSignature Email

This setting tells Apache which character set should be used as the default for any content that is defined in the HTTP headers.

AddDefaultCharset UTF-8

The server-status provides real-time status information about the active Apache server. Access restrictions can be applied similar to the example. This is accessible by typing http://localhost/server-status.

<Location /server-status>
    SetHandler server-status
    Order deny,allow
    Deny from all
    Allow from
    Allow from

The server-info provides real-time configuration information about the active Apache server. Access restrictions can be applied similar to the example. This is accessible by typing http://localhost/server-info.

<Location /server-info>
    SetHandler server-info
    Order deny,allow
    Deny from all
    Allow from
    Allow from

We have only covered some of the more common settings here. Remember the provided manual is the best source of information to assist with further configuration and detailed assistance, assuming you get your server running.

Starting the Server

The Apache server runs under the "httpd" service name, so lets set the appropriate runlevels and then confirm they are correct.

[bash]# chkconfig --level 345 httpd on
[bash]# chkconfig --list httpd

The server can now be started and the system log should be checked for any initialisation or runtime errors.

[bash]# /etc/init.d/httpd restart
[bash]# grep httpd /var/log/messages
[bash]# tail /var/log/httpd/error_log

Creating a Favicon

Most of the latest web browsers now support the use of favicons, which are a small image (icon) file located in your DocumentRoot directory. When a clients browser requests a web page, it also requests the favicon and if its available, displays the favicon in the address field next to the web sites URL. The favicon is able to store a few different sizes in the one image, this allows it to display the appropriate size image when your web site is bookmarked or saved as a desktop shortcut. There are a few sites on the Internet that have free favicons available for download, or you can generate your own to provide a more personal feel for your site.

Creating your own favicon can be a bit fiddly, so we'll automate the process with a small propose written script. Firstly we need to install the netpbm image manipulation applications using the following command.

[bash]# yum install netpbm-progs

Now we can create our "makefavicon" shell script. This script will convert any size image file into the three standard 16x16, 32x32 and 48x48 files required to create a standard favicon file. The default image files that will be excepted by the script are PAM, PNM, PPM, PGM and PBM; other images files can be easily converted to the required image format by using one of the many image tools available in the netpbm-progs suite of applications (there are approx 200 apps, mostly image conversion). Type "man netpbm" at the command prompt for more info on the other applications available in netpbm.

[bash]# vi /bin/makefavicon

if [ -z $1 ] ; then
    echo -e "\\nUsage: \"makefavicon <image_filename.png>\"\\n"
    echo -e "Suitable file types are: PAM, PNM, PPM, PGM, or PBM.\\n"

rm -f favicon.ico

pamscale -linear -xsize=48 -ysize=48 $1 > tmp_logo48.ppm
pamscale -linear -xsize=32 -ysize=32 $1 > tmp_logo32.ppm
pamscale -linear -xsize=16 -ysize=16 $1 > tmp_logo16.ppm

pnmquant 256 tmp_logo48.ppm > tmp_logo48x48.ppm
pnmquant 256 tmp_logo32.ppm > tmp_logo32x32.ppm
pnmquant 256 tmp_logo16.ppm > tmp_logo16x16.ppm

ppmtowinicon tmp_logo16x16.ppm tmp_logo32x32.ppm tmp_logo48x48.ppm -output favicon.ico

rm -f tmp_logo*.ppm

Once we have created our script, we need to grant execution permissions on the file.

[bash]# chmod +x /bin/makefavicon

The script is executed at the command prompt with the image to be converted to a favicon listed as an argument to the script.

[bash]# makefavicon image_file.ppm

To convert a PNG file to a favicon, execute the following command which firstly converts the file to PNM format, then it can be converted with the script.

[bash]# pngtopnm -mix pic_file.png > file_to_convert.pnm
[bash]# makefavicon file_to_convert.pnm

The icon file now needs to be placed inside the Apache server's document root directory.

[bash]# cp favicon.ico /var/www/html/

The favicon.ico file will be automatically passed to remote web browsers as they connect to your server (no need to edit html pages), however you are able to manually place inline references to the favicon if required; this would mainly be done if you wish your pages to use different favicon sets.

[bash]# vi /var/www/html/index.html
<link rel="icon" href="favicon.ico" type="image/x-icon">
<link rel="shortcut icon" href="favicon.ico" type="image/x-icon">

User Directories

The Apache server is capable of serving web pages straight from the directories of your system user accounts. This allows all the system users the ability to run their own web sites which are hosted off the main server. This is exactly the same way that many ISPs provide websites for their customers and its relatively easy to enable.

The important thing to be aware of firstly, is that a site hosted from a users home directory needs to have a tilde "~" placed in front of the users name like in the following two examples.

Home Directory
Users URL

To enable the public folders for the users, locate the following section in the configuration file and make the adjustments required similar to the example. The "public_html" value identifies the directory name inside the users home directory where the files will be served from. This value can be changed if you feel its easier for your users to understand and if you do change it, make the change early in the servers configuration and not after all your users have already established their web sites. This may save some later problems.

[bash]# vi /etc/httpd/conf/httpd.conf
<IfModule mod_userdir.c>
#    UserDir disable
     UserDir public_html
<Directory /home/*/public_html>
    AllowOverride FileInfo AuthConfig Limit
    Options MultiViews Indexes SymLinksIfOwnerMatch IncludesNoExec
        Order allow,deny
        Allow from all
    <LimitExcept GET POST OPTIONS>
        Order deny,allow
        Deny from all

File Permissions

One of the biggest problems that most people face when setting up public html folders, is the permissions required for the server to access and serve the pages. The server does not have access to the users home directories by default, so the following changes need to be made by the user (or root) to allow access.

The best way for users to upload their webpages to the server is by using the FTP service on the localhost. If FTP is going to be made available for public access, ensure that users are chroot jailed inside their own home directories, this prevents unwanted users wondering around the filesystem (See chap 14 for FTP details).

chmod 701
chmod 705 /home/*/public_html
chmod 604 /home/*/public_html/*.html
chmod 705 /home/*/public_html/cgi-bin
chmod 705 /home/*/public_html/cgi-bin/*.cgi        (or *.pl)

It can be time consuming for the local administrator to create all the public html folders and set the required permissions, or the user may not know how or set them correctly. This configuration process can be automated by making adjustments to the local skeleton profile, then when any new user accounts are created all of the directories and permissions are already set and ready for use.

[bash]# mkdir /etc/skel/public_html
[bash]# mkdir /etc/skel/public_html/cgi-bin
[bash]# chmod 705 /etc/skel/public_html
[bash]# chmod 705 /etc/skel/public_html/cgi-bin/

Caution !! Not all Linux distributions have the skeleton profile located in the same area.

A very basic HTML page can also be added to the skeleton profile which will be available to the Apache server as soon as a new account is created. This is not necessarily needed, but can assist new users by showing them the location of the relevant file.

[bash]# echo 'Test User Page !' > /etc/skel/public_html/index.html
[bash]# chmod 604 /etc/skel/public_html/index.html

Some users like to run their own CGI scripts which allows them to interact with the localhost to some degree. As with the above example, a basic CGI script can be created for the skeleton profile to assist new users. It also provides the user with a basic working script for testing purposes.

[bash]# vi /etc/skel/public_html/cgi-bin/test.cgi
print "Content-type: text/html\n\n";
print "Hello, World.";
[bash]# chmod 705 /etc/skel/public_html/cgi-bin/test.cgi

Note !! Setting cgi-bin files, directories and permissions in the skeleton profile DOES NOT enable CGI for local users, this must be configured manually in the httpd.conf file before the service is available.

Forbidden Errors (SELinux)

You may experience a "forbidden error" when attempting to access a users public web site (http://localhost/~alice), this is generally because the permissions are either set incorrectly, or SELinux is set to "Enforcing" mode which blocks the standard suexec call needed by the Apache server. Common error is the "/home/username" permissions.

To temporarily disable SELinux so you can test the access permissions, type "setenforce 0" at the command prompt. Typing "setenforce 1" sets SELinux back to Enforcing mode.

Use the following commands to permanently adjust the SELinux file security context so Apache can access user's public web sites.

### SELinux ONLY - Enable User Website
[bash]# setsebool -P httpd_enable_homedirs true
[bash]# chcon -v -R -h -u user_u -t httpd_user_content_t /home/*/public_html
### SELinux ONLY - Disable User Website
[bash]# setsebool -P httpd_enable_homedirs false
[bash]# chcon -v -R -h -u user_u -t user_home_t /home/*/public_html

Enabling CGI Scripts

A CGI (Common Gateway Interface) provides a means for web content to interact with programs or applications running on the localhost server, like calling the current date or uptime. The default configuration of Apache allows global CGI scripts for root, however it must be manually configured for public users.

Because CGI scripts are able to call local programs and applications on the server, you should consider whether local public users should be allowed to run their own applications. Many ISPs do not allow their customers to execute CGI on their servers for fear of malicious code or content, and for good reason. Some smaller or more trusted environments may allow public CGI scripts, so this is how we set them up.

[bash]# vi /etc/httpd/conf/httpd.conf

The ScriptAlias directive is similar to the standard Alias directive, however it tells the system that the contents of the directory should be treated as system scripts and not as standard HTML content. The following are the global cgi-bin settings for the main server, it is normally enabled by default because root should be trusted, we hope.

ScriptAlias /cgi-bin/ "/var/www/cgi-bin/"
<Directory "/var/www/cgi-bin">
    AllowOverride None
    Options None
    Order allow,deny
    Allow from all

To allow public CGI, we need to define the "public_html/cgi-bin" directory, remember if you changed the "public_html" directory for the users in the earlier configuration, then ensure the following suits the adjustments.

The AddHandler directive provides the means for any cgi-scripts to be handled that are located outside the global cgi-bin directory, which in this case is the public users home directories.

<Directory /home/*/public_html/cgi-bin>
    Options ExecCGI
    SetHandler cgi-script
AddHandler cgi-script .cgi .pl

Authenticating Users

Main Server Authentication

Restricting access to resources on the web server can be achieved a few different ways. The preferred method for controlling access throughout the main server filesystem, is to place individual directives into the httpd.conf configuration file for each area that needs any restrictions.

The following example provides security to the /var/www/html/private directory (http://localhost/private), and will only allow valid users from the authusers file if they are listed in the private group contained in the authgroups file.

Caution !! It is important to note that the authorisation files are not located inside the "DocumentRoot" structure, otherwise they could be downloaded if not properly secured.

# Provides security for ""
<Directory "/var/www/html/private">
    AuthType Basic
    AuthName "Private Area - Authorisation Required"
    AuthUserFile /etc/httpd/conf/authusers
    AuthGroupFile /etc/httpd/conf/authgroups
    Require group private
#    Require valid-user

    Options Indexes FollowSymLinks
    AllowOverride None

The authgroups file contains a listing of users that have been placed into logical groups depending on the areas of access they will be granted. When a users authorisation is check, the username must correspond to the group name in the authgroups file, as specified in the "Require group private" directive. Only users alice, bob and jane are authorised to access the private area.

[bash]# vi /etc/httpd/conf/authgroups
private: alice bob jane
friends: mark linda andrew
superusers: linda bob

The authusers file contains a listing of usernames and hashed password values which are checked for authorisation. For a small office or home server, the directive "Require valid-user" would be more suitable than managing a list of groups and users as it will match any user in the file.

[bash]# touch /etc/httpd/conf/authusers
[bash]# htpasswd /etc/httpd/conf/authusers alice

Warning !! You should always use the touch command to create a username/password file, using the wrong command line option (-c) will overwrite an existing file.

User (public_html) Authentication

General users must manage their authentication slightly differently because they don't have access to the main configuration file for the server, this is where the AccessFileName (.htaccess) directive comes into play.

The user needs to place a .htaccess file into the directory they intend on securing, and then placing the authorisation directives into the file like in the example.

[bash]$ vi .htaccess
AuthType Basic
AuthName "Alice's Private Area"
AuthUserFile .htauthusers
Require valid-user

The .htauthusers file is now used to contain the username and password details, so the system can check for authentication.

[bash]$ touch .htauthusers
[bash]$ htpasswd .htauthusers alice

You should notice the difference in the second example, where the authorisation directive is now simply "Require valid-user", no large group files are necessary.

If problems occur and the authentication module is not being enforced for public_html directories, ensure the following directive has been specified in the main configuration file for public web sites.

AllowOverride AuthConfig

Caution !! You should be aware there is a possibility that usernames and passwords are able to be intercepted during authentication by malicious users. This can be secured by using encryption techniques like SSL and TLS.

Virtual Hosts

Virtual hosting is the ability of a single server to host more than one website and maintaining the appearance that they are two entirely different servers. There are two different types of virtual hosting:
There are pros and cons about both types, however for a home set up we are more concerned with a single IP address, so we will cover name based virtual hosting. Its also the easiest.

When working with virtual hosts, its always a good idea to set up your own DNS server for testing (if you're not already running one). This allows you to create your own new domain zone which is internal to your own network, if everything falls down during development, then the rest of the Internet will not be effected by any zones that you have configured. You can also easily add a new domain zone for each new virtual host you need to test.

The last section of the httpd.conf file is dedicated to virtual hosting, so lets edit the file and head south.

[bash]# vi /etc/httpd/conf/httpd.conf

The following example shows two different domains ( and being hosted from the main server. Both hosts are using a separate directory as the DocumentRoot, and are also logging to different access and error logs. Including the servers original domain of, thats now three domains the server is hosting.

NameVirtualHost *:80

#Virtual Host 1 - EXAMPLE.ORG
<VirtualHost *:80>
    ServerAdmin [email protected]
    DocumentRoot /var/webhosts/
    CustomLog logs/ common
    ErrorLog logs/

#Virtual Host 2 - EXAMPLE.NET
<VirtualHost *:80>
    ServerAdmin [email protected]
    DocumentRoot /var/webhosts/
    CustomLog logs/ common
    ErrorLog logs/

Name based virtual hosting relies on a domain name being passed to the server when a web page is requested, the server sees the domain name in the request and serves the page from the virtual host matching the domain name. The most important aspect is there must be a valid DNS entry for the virtual host, otherwise a client won't be able to send the proper request to the server.

Using SSL Certificates

Sending usernames and passwords in cleartext over the Internet risks the possibility that they may be intercepted, also doing online banking or other financial transactions using clear text is a major gamble that your details will be captured. By encrypting our communication so that only the user and the server are able to access the information, we stand a far greater chance of ensuring our details will not be disclosed to some unknown third parties.

The Apache server utilises the Secure Sockets Layer (SSL) to create a secure link between itself and the connecting web brower, so that any information being passed is hidden from view. This does not stop any data from being captured, but it changes the information using cryptographic algorithms which would take an attacker an awfully long time to decrypt.

There are a few points you need to be aware of before implementing SSL certificates:
Apache uses the SSL module which in-turn accesses the OpenSSL libraries needed to implement the cryptographic mechanisms. Being a module, the configuration file is located in a separate area from the main configuration.

Configuration File:

To enable SSL we need to generate an asymmetric key pair. This means there are two keys generated (public and private) which are mathematically matched to complement each other; only the public key can encrypt/decrypt anything from (or to) the private key, and vice versa. The private key must be kept secure, while the public key can be given to anyone that needs it, thats why its called the public key.

Now that we are going to be making cryptographic keys, we need a secure environment in which to create and store them. The following is suitable for a home environment.

[bash]# mkdir /root/SSL_Certs
[bash]# chmod 600 /root/SSL_Certs
[bash]# cd /root/SSL_Certs

Step 1:   This following command creates a private key for the server. It also creates a certificate signing request file which contains a copy of your public key and some personal details that identify you and the server.

If your web site is going to be used to offer public services or e-commerce applications, the digital certificate should be signed by a proper Certifying Authority (CA). The "certsignreq.csr" file can now be sent to a CA so it can be signed; there is a fee involved for this server. The contents of the "certsignreq.csr" file can be read by anyone (its public information), so copying and pasting the details into a CAs website is not a security risk.

[bash]# openssl req -newkey rsa:1024 -keyout private.key -out certsignreq.csr
Generating a 1024 bit RSA private key
writing new private key to 'private.key'
Enter PEM pass phrase:              ENTER PASSPHRASE HERE
Verifying - Enter PEM pass phrase:  ENTER PASSPHRASE HERE
You are about to be asked to enter information that will be incorporated
into your certificate request.
What you are about to enter is what is called a Distinguished Name or a DN.
There are quite a few fields but you can leave some blank
For some fields there will be a default value,
If you enter '.', the field will be left blank.
Country Name (2 letter code) [GB]:AU
State or Province Name (full name) [Berkshire]:QLD
Locality Name (eg, city) [Newbury]:Brisbane
Organization Name (eg, company) [My Company Ltd]:Miles Brennan
Organizational Unit Name (eg, section) []:Home Linux Server
Common Name (eg, your name or your server's hostname) []
Email Address []:[email protected]

Please enter the following 'extra' attributes
to be sent with your certificate request
A challenge password []:secretword
An optional company name []:

Caution !! The servers name inside the certificate should be the fully qualified hostname that a user is connecting to, otherwise the web browser will throw the user a warning message. If the servers name is but has an alias to which is used for people to connect, then the certificate should have the name of

Step 2:   If you intend on using SSL simply for your own use, and only your friends and family are going to connect, then you can create your own self-signed digital certificate for this purpose; you don't need a CA signed cert file.

Using your own self-signed digital certificate causes the browser to query the certificate when a user connects to the website, the certificate must be manually accepted before the user can proceed. In this example we are creating a self-signed certificate with a five year life (-days 1825).

[bash]# openssl rsa -in private.key -out signingkey.key
[bash]# openssl x509 -in certsignreq.csr -out selfsigned_digicert.crt -req -signkey signingkey.key -days 1825

Step 3:   The original private key that was created used a passphrase to provide it with extra protection in case someone was to gain physical access to the key file. When the Apache server starts, it asks for the passphrase for the private key; this extra precaution stops someone being able to impersonate your website if they get a copy of your private key.

If the server needs to be restarted and no one is available to enter the passphrase for the server, then it will simply wait and the server will not start. This passphrase checking can be removed using the following sequence of commands, remember to secure the file so only the root user can access it.

[bash]# mv private.key private.key.withpassphrase
[bash]# openssl rsa -in private.key.withpassphrase -out private.key
[bash]# chmod 0400 private.key

Step 4:   After the keys and certificate have been prepared, they can be copied across to the location where the Apache server will load them automatically at runtime.

[bash]# cp private.key /etc/pki/tls/private/localhost.key
[bash]# cp selfsigned_digicert.crt /etc/pki/tls/certs/localhost.crt

Step 5:   If you configured your server with a self-signed certificate as a temporary measure, then the temporary certificate can be easily replaced with the real one when it is returned from the CA.

[bash]# cp CAsigned_digicert.crt /etc/httpd/conf/ssl.crt/server.crt

The certificate signing request can be deleted after the CA has returned your new digital certificate. If your private key file is ever compromised or lost, you will need to regenerate new keys starting from step one again.

Forcing SSL Mode

Now that the server is enabled with SSL, all interactions with the server that deal in usernames, passwords, financial or personal details can (and should) be sent using the protocol. This is most simply done by typing https in the address bar instead of http, this can also be coded into any webpages to automate the process. But things go wrong and the little 's' gets forgotten.

The server has another module called "mod_rewrite" which allows an incoming URL request to be rewritten before the server responds with any web pages. The rewrite module now provides a way to force any incoming connection request to the SSL protocol, assuming some predefined criteria like a secure server directory.

[bash]# vi /etc/httpd/conf.d/mod-rewrite.conf

This small rewrite code can be placed in its own file (so all rewrite rules can be grouped together), then any request that gets sent to the "webmail" folder will be forced into SSL mode and your users can enter their details in confidentiality. The rewrite log can be used for debugging if need be.

# Rewrite Rules.
RewriteEngine On
RewriteCond %{HTTPS} !=on
RewriteRule ^/webmail/(.*) https://%{SERVER_NAME}/webmail/$1 [R,L]

#Debug Rewrite Rules
#RewriteLog /var/log/httpd/rewrite_engine_log
#RewriteLogLevel 3

For more information on the rewrite module, refer to the URL Rewriting Guide in the provided Apache manual: http://localhost/manual/misc/rewriteguide.html

Caution !! The SSL protocol does have some CPU overheads, so only use it where its most practical. Don't force it for the whole server unless you are providing a particular service to customers.

Webmail Configuration

SquirrelMail is a PHP based web application that runs on the Apache server and allows your users the ability to log in and read their email from a remote location, its webmail. The application only supports 'imap' mailboxes and not POP3, so your email server needs to provide access using imap (POP3 can still be used for standard mail readers). The dovecot package supports both protocols and also supports TLS encryption. SquirrelMail has many extra plugin modules that have been written for it, and its simply a matter of downloading the plugin and running a configuration script; its that easy.

The package has two configuration files, one that enables the application for Apache and another containing the main PHP settings. The Apache configuration details an alias that points to the location of the main SquirrelMail directory, this would be viewed at http://localhost/webmail.

Configuration File:
Alias /webmail /usr/share/squirrelmail

The main PHP configuration file should be backed up before making any changes.

[bash]# cp /etc/squirrelmail/config.php /etc/squirrelmail/config.php.original
[bash]# vi /etc/squirrelmail/config.php

The PHP settings are fairly easy to understand just by looking at them. You should only need to worry about the domain name ($domain), where the imap mailboxes are located ($imapServerAddress), and where to send outgoing emails for processing ($smtpServerAddress). If the webmail application is being run on the email server (like we're doing), then leave the settings for localhost.

$domain                 = '';
$imapServerAddress      = 'localhost';
$imapPort               = 143;              <-- plain IMAP protocol running on localhost (server)
$useSendmail            = true;
$smtpServerAddress      = 'localhost';
$smtpPort               = 25;
$sendmail_path          = '/usr/sbin/sendmail';
$pop_before_smtp        = false;
$imap_server_type       = 'uw';

One of the big queries that always gets asked about any webmail system, is how to change the size of the file attachments users can send. Then look no further, this in fact is a PHP setting. You need to change the setting in the main PHP ini file, and it should be set to the same value the mail server is configured to accept.

[bash]# vi /etc/php.ini
post_max_size = 50M
upload_max_filesize = 50M
memory_limit = 64M

Your webmail application should now be configured.

Caution !! If you are accessing webmail from outside your network, use SSL where possible.

If you receive an error from squirrelmail stating "Error connecting to IMAP server: localhost", it means that IMAP is not running on the local server using port 143. This is because we only allowed SSL connections during our mail server configuration (Chapter 12), the following adjustment to Dovecot can be made to allow IMAP on the localhost server.

This setting only allows insecure (plain) IMAP connections from the localhost server, which is ideal for webmail access. All other mail orientated connections are forced to use either IMAPS or POP3S, both secure protocols.

[bash]# vi /etc/dovecot.conf
protocols = imap imaps pop3s

protocol imap {
listen =
ssl_listen = *
ssl_disable = no

Once Squirrel Mail has been installed, it can be configured on the server by using the configuration perl script. This script can be used to configure the many plugins available for Squirrel Mail, including the configuration of an LDAP shared address book; conveniently documented in Chapter 20.

[bash]# cd /usr/share/squirrelmail/config
[bash]# ./

Home Next