== Apache Practical, Week 4 ==

This practical is about installing and configuring an Apache web server. Since
we need special features (e.g. support for PCRE), we cannot just install the
version provided by our package manager. Instead, we have to build Apache from
source.

At the end of the practical, we should be able to access public pages on the
web server but also private pages which require HTTP authentication.

=== Problem 1: Dependencies issue with APR and APR-Util ===

When we try to configure the build of Apache for the first time, it complains
about missing dependencies: APR (Apache Portable Runtime) and APR-util (Apache
Portable Runtime Utility). i.e. a command looking like this:

    $ ./configure --prefix=<pfx> --with-included-apr --with-pcre=/usr/local/pcre

gives this output:

    > configure: error: Bundled APR requested but not found at ./srclib/.
    > Download and unpack the corresponding apr and apr-util packages to ./srclib/.

==== Resolution ====

Because these two libraries have to be linked with Apache during the build
process, we have to install them in order to be able to build.

Apache build system already provides us a directory './srclib/' that can be used to
build the libraries along with the Apache itself. It saves us the time of
building them separately. So all we have to do is download the source code of
these two libraries and extract them is './srclib/'

    $ wget -q http://mir2.ovh.net/ftp.apache.org/dist//apr/apr-1.5.1.tar.gz
    $ tar xzf apr-1.5.1.tar.gz -C ./srclib/
    $ wget -q http://apache.websitebeheerjd.nl//apr/apr-util-1.5.4.tar.gz
    $ tar xzf apr-util-1.5.4.tar.gz -C ./srclib/

Since Apache build process expects directories named 'apr' and 'apr-util', we can
create symlinks.

    $ ln -s apr-1.5.1 srclib/apr
    $ ln -s apr-util-1.5.4 srclib/apr-util

Another attempt of running './configure' confirms us that APR and APR-util are
now in place and ready to be built.

=== Problem 2: pcre-config is not found

Even though, there is no more dependency issues with APR, the build process now
complains about a missing binary: 'pcre-config'

    > configure: error: pcre-config for libpcre not found. PCRE is required and available from http://pcre.org/

==== Resolution ====

'pcre-config' and eventually most of '-config' binaries are used by build
processes to portably retrieve linker and compiler flags for a given library.
On Debian and Ubuntu, these binaries are often provided by the '-dev' packages.
In our case, it is 'libpcre3-dev'.

    $ sudo apt-get install libpcre3-dev

'./configure' now runs without any issue. We can then build and install Apache.

=== Problem 3: Need of restarting the web server ===

During the configuration of the HTTP authentication, we have to restart the web
server each time we make a single modification because 'httpd.conf' is read at
startup. It becomes very cumbersome when we are not familiar with the syntax on
the configuration file.

==== Resolution ====

Apache provides us a way to use configuration files that are read on the fly.
We often refer to these files as '.htaccess'. In our case, we can configure the
authentication on the fly by replacing in 'httpd.conf'

    AllowOverride None

by

    AllowOverride AuthConfig

and restarting the web server. This way, we can write our configuration
directives 'htdocs/private/.htaccess' and test them without reloading Apache.

=== Problem 4: Web Browsers keep the authentication details ===

Most web browsers, until they are restarted, save your credentials whenever you
successfully pass HTTP authentication so that you do not need to provide them
again when you reload the same page. It is very annoying when we are testing
our HTTP authentication because we need to restart our browser after each
successful attempt.

==== Resolution ====

Instead of using a web browser to test our authentication, we can use 'curl'
which is a tool capable of executing a HTTP request, print the answer and quit
without saving the credentials.

For that, we first have to install it if it is not already present:

    $ sudo apt-get install curl

Then we can perform queries to our web server (the '-u' option allows to provide
a 'user:password' pair).

===== Examples =====

- Failing to access /private without providing user/password:

    $ curl http://csvm2C4E.kent.ac.uk/private/
    > <!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 2.0//EN">
    > <html><head>
    > <title>401 Unauthorized</title>
    > </head><body>
    > <h1>Unauthorized</h1>
    > <p>This server could not verify that you
    > are authorized to access the document
    > requested.  Either you supplied the wrong
    > credentials (e.g., bad password), or your
    > browser doesn't understand how to supply
    > the credentials required.</p>
    > </body></html>

- Failing to access /private by providing a wrong password:

    $ curl http://csvm2C4E.kent.ac.uk/private/ -u admin:wrong_pass
    > <!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 2.0//EN">
    > <html><head>
    > <title>401 Unauthorized</title>
    > </head><body>
    > <h1>Unauthorized</h1>
    > <p>This server could not verify that you
    > are authorized to access the document
    > requested.  Either you supplied the wrong
    > credentials (e.g., bad password), or your
    > browser doesn't understand how to supply
    > the credentials required.</p>
    > </body></html>

- Successing to access /private by providing both a good user name and password

    $ curl http://csvm2C4E.kent.ac.uk/private/ -u admin:good_pass
    > <html>
    >     <body>
    >         <p>
    >         This content is private. If you can read this message, it means that you have successfully passed HTTP authentication.
    >         </p>
    >     </body>
    > </html>
    >