use *.asciidoc(i) extension instead of *.adoc(i)

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

1 files changed, 134 insertions, 0 deletions

diff --git a/apache.asciidoci b/apache.asciidoci
new file mode 100644
index 0000000..8c3b259
--- /dev/null
+++ b/apache.asciidoci
@@ -0,0 +1,134 @@
+== 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).
+
+Only interesting excerpts of the output is shown below
+
+.Failing to access '/private' without providing user/password:
+==========
+
+    $ curl http://csvm2C4E.kent.ac.uk/private/
+    > <title>401 Unauthorized</title>
+
+==========
+
+.Failing to access '/private' by providing a wrong password:
+==========
+
+    $ curl http://csvm2C4E.kent.ac.uk/private/ -u admin:wrong_pass
+    > <title>401 Unauthorized</title>
+
+=========
+
+.Successing to access '/private' by providing both a good username and password
+=========
+
+    $ curl http://csvm2C4E.kent.ac.uk/private/ -u admin:good_pass
+    > This content is private. If you can read this message, it means that you have successfully passed HTTP authentication.
+
+=========
+