added the first practical

Signed-off-by: Olivier Gayot <duskcoder@gmail.com>

3 files changed, 168 insertions, 0 deletions

diff --git a/Makefile b/Makefile
new file mode 100644
index 0000000..edec2ca
--- /dev/null
+++ b/Makefile
@@ -0,0 +1,12 @@
+SRC = $(wildcard *.adoc)
+
+HTML = $(SRC:.adoc=.html)
+PDF = $(SRC:.adoc=.pdf)
+
+all: $(HTML) $(PDF)
+
+%.html: %.adoc $(wildcard *.adoci)
+	asciidoc $<
+
+%.pdf: %.adoc $(wildcard *.adoci)
+	a2x $< -L
diff --git a/apache.adoci b/apache.adoci
new file mode 100644
index 0000000..e7d5925
--- /dev/null
+++ b/apache.adoci
@@ -0,0 +1,155 @@
+== 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>
+    >
diff --git a/practicals.adoc b/practicals.adoc
new file mode 100644
index 0000000..126d24f
--- /dev/null
+++ b/practicals.adoc
@@ -0,0 +1 @@
+include::apache.adoci[]