This document is a DRAFT...and may contain inadvertently misleading or other erroneous information. Caveat lector.

DISCLAIMER: This page contains details and instructions for setting up web server configurations within DICE (the Distributed Informatics Computing Environment), using the LCFG management tools. It does not apply to any other environment.

A detailed step-by-step example of setting up a web-server using apacheconf

This example shows the set-up process for a new web server (running Apache 2.0) on a vanilla DICE machine. All configuration is done using resources defined in the machine's profile. The necessary profile entries are highlighted thus, with required commands thus. So, to set up a server without worrying about details and explanations, just add the profile entries and run the commands.

For other apacheconf notes, see Simon's Musing's, Using Apacheconf with CoSign, or Apacheconf slides (from which some of the information below may be drawn).

Configuring a basic web service

Overview:

  • add #include files
  • define and configure a virtual host
  • configure and run apache via "om"

In detail:

  • edit the profile and define the Apache version

For Apache 2.0 and greater:

#include <dice/options/apacheconf-2.h>

(which, in turn, includes <apacheconf.h>)

om updaterpms run

This installs the relevant lcfg-apacheconf RPM and sets initial apacheconf resources (setting run-time user & group, enabling run at boot-time, &c).

  • define the service and declare (add) a virtual host

It is assumed that all web services will be defined as virtual hosts (the automatic configuration for a default server does not currently work - for example, the apacheconf.port resource generates an Apache 1.3 Port directive, rather than the Apache 2.2 Listen directive).

To set up a web service on host "webhost" (using the name as the resource tag), add the tag to the vhosts resource list (replacing "webhost" with the chosen service host name - which must have a valid DNS entry, as it is used to get the IP address for the NameVirtualHost directive):

!apacheconf.vhosts	mADD(webhost)

(this will create a default "Listen 80" directive, and a placeholder "VirtualHost" section, in the resulting httpd.conf file)

  • add virtualhost name:

!apacheconf.vhostname_webhost	mSET(webhost.inf.ed.ac.uk)

(no additional port definition is required if the default is being used). If another port is required, define a non-default port (e.g 8080):

    !apacheconf.vhostport_webhost	mSET(8080)

(Note that using just the vhostport_webhost resource will set the default "Listen" directive to match - this may not always be what you want.)

  • check/create directory structure

The /etc/httpd structure is available by default (as part of a standard installation). Files in this hierarchy are currently provided by the following RPMS:

    gitweb-1.6.5.2
    htdig-web-3.2.0b6
    httpd-2.2.3
    httpd-manual-2.2.3
    mailman-2.1.9
    mod_auth_kerb-5.1
    mod_auth_mysql-3.0.0
    mod_auth_pgsql-2.0.3
    mod_authz_ldap-0.26
    mod_dav_svn-1.4.2
    mod_nss-1.0.3
    mod_perl-2.0.4
    mod_python-3.2.8
    mod_ssl-2.2.3
    php-5.1.6
    squid-2.6.STABLE21
    squirrelmail-1.4.8
    trac-0.10.4
    webalizer-2.01_10

Note that the above list of RPMs only relates to files directly below /etc/httpd, and not to the contents of any directories linked to from that location (such as /etc/httpd/modules or /etc/httpd/logs).

Any manual changes to the /etc/httpd structure or associated RPMs must take these dependencies into account. However, for a default installation no action should be required.

  • configure & test

Once the profile has compiled, running:

    om apacheconf configure

- will create a new httpd.conf file, containing the necessary directives for a basic web service:

    Listen 80
    User apache
    Group apache

    NameVirtualHost 129.215.25.68:80

    <VirtualHost webhost.inf.ed.ac.uk:80>
      ServerName webhost.inf.ed.ac.uk
    </VirtualHost>

The usual start (and configure) procedure for apache, is to run:

om apacheconf start

This should be all that is necessary for a very basic web server, which should serve web pages from /var/www/html.

(Note that the "om apacheconf configure" command is not strictly necessary, unless the configuration files need to be generated without starting apache, as the start method runs the configure method.)

Configuring a secure, authenticated web service

Overview:

For the secure service:

  • define SSL service
  • generate certificates
  • configure SSL

For the authenticated service:

  • configure CoSign

In detail:

  • define SSL service

In addition to the basic configuration above, an authenticated service requires an extra virtual host tag and name to be defined for the authenticated service (the tag string is internal to the profile, and can be anything you like - in this example, "webhostSSL" is used):

!apacheconf.vhosts               mADD(webhostSSL)
!apacheconf.vhostname_webhostSSL mSET(webhost.inf.ed.ac.uk)

  • generate certificates

The certification mechanism should now be configured which, at its most basic, consists of adding X509 resources by means of the <x509-client.h> header (and the _X509_SERVICE macro which it defines):

#include <dice/options/x509-client.h>
_X509_SERVICE(webhost)

To configure X509:

om x509 configure

- which creates the key and certificate files:

    /etc/httpd/conf/webhost.chain
    /etc/httpd/conf/webhost.key
    /etc/httpd/conf/webhost.crt

The usual start (and configure) procedure for x509 is to run:

om x509 start

The x509 resources can then be used to configure SSL. Note that this procedure is only necessary at setup (the x509 component will be automatically started at boot time).

To obtain a new (local, EdUni -signed) certificate via the x509 component, simply move the .crt file to one side and re-run the x509 component. To obtain a new externally-signed certificate (via JANET, currently using Comodo), see Toby's web page.

  • configure SSL

To configure an SSL connection, include the apacheconf-ssl.h header and set the enable flag:

#include  
!apacheconf.vhostssl_webhostSSL        mSET(yes)

...this loads relevant modules, sets SSL values, and enables SSL:

    LoadModule ssl_module	  /usr/lib/httpd/modules/mod_ssl.so
    ...
    Listen 443
    ...
    SSLPassPhraseDialog           builtin
    SSLSessionCache               shm:logs/ssl_scache(512000)
    SSLSessionCacheTimeout        300
    SSLMutex		          file:logs/ssl_mutex
    SSLRandomSeed	          startup builtin
    SSLRandomSeed		  connect builtin
    ...
    <VirtualHost webhost.inf.ed.ac.uk:443>
        ServerName webhost.inf.ed.ac.uk
	SSLEngine On
	SSLCertificateFile	  /etc/httpd/conf/webhost.crt
	SSLCertificateKeyFile     /etc/httpd/conf/webhost.key
	SSLCertificateChainFile   /etc/httpd/conf/webhost.chain
    </VirtualHost>

Note that the resource apacheconf.vhostssl_webhost needs to be set (to "true" or "yes") in order for correct SSL configuration (without it, port 80 is used and SSLEngine is not enabled).

This should be all that is necessary for a basic secure-connection server-authenticated web service.

Note that the above describes the processes underlying a web service, and does not exactly describe the procedures for setting up such a server - for example, there is no need to explicitly configure the x509 and apacheconf components (there is also no specific mention of running updaterpms to installed the necessary packages needed).

  • configure CoSign

Include the apacheconf-cosign.h header and set user and group ownership with _X509_SERVICE_OWNERSHIP macro (defined in x509-client.h)

#include <dice/options/apacheconf-cosign.h>

_X509_SERVICE_OWNERSHIP(webhost,apache,apache)

Then start cosign and restart apache:

om cosign start
om apacheconf restart

-- RogerBurroughes - 30 Mar 2010

Topic revision: r9 - 29 Jul 2014 - 08:33:38 - RogerBurroughes
 
This site is powered by the TWiki collaboration platformCopyright © by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
Ideas, requests, problems regarding TWiki? Send feedback
This Wiki uses Cookies