Chapter 5. Complete Working Examples

5.1. mod_cluster Example

This section contains a set of example configurations for a complete working example of how to use mod_cluster on a Red Hat Enterprise Linux system.

Load Balancer

To setup JBoss Core Services as a proxy server listening on localhost, create a configuration file in JBCS_HOME/httpd/conf.d/mod_cluster.conf and add the following:

LoadModule proxy_cluster_module modules/mod_proxy_cluster.so
LoadModule cluster_slotmem_module modules/mod_cluster_slotmem.so
LoadModule manager_module modules/mod_manager.so
LoadModule advertise_module modules/mod_advertise.so

MemManagerFile cache/mod_cluster

<IfModule manager_module>
  Listen 6666
  <VirtualHost *:6666>
    <Directory />
      Require ip 127.0.0.1
    </Directory>
    ServerAdvertise on
    EnableMCPMReceive
    <Location /mod_cluster_manager>
      SetHandler mod_cluster-manager
      Require ip 127.0.0.1
   </Location>
  </VirtualHost>
</IfModule>

Worker Configuration for Tomcat

Edit JWS_HOME/tomcat/conf/server.xml, and add the following Listener element to configure a Tomcat worker node:

<Listener className="org.jboss.modcluster.container.catalina.standalone.ModClusterListener" advertise="true"/>

Example iptables Firewall Rules

The following are a set of example firewall rules using iptables, for a cluster node on the 192.168.1.0/24 subnet.

/sbin/iptables -I INPUT 5 -p udp -d 224.0.1.0/24 -j ACCEPT -m comment --comment "mod_cluster traffic"
/sbin/iptables -I INPUT 6 -p udp -d 224.0.0.0/4 -j ACCEPT -m comment --comment "JBoss Cluster traffic"
/sbin/iptables -I INPUT 9 -p udp -s 192.168.1.0/24 -j ACCEPT -m comment --comment "cluster subnet for inter-node communication"
/sbin/iptables -I INPUT 10 -p tcp -s 192.168.1.0/24 -j ACCEPT -m comment --comment "cluster subnet for inter-node communication"
/etc/init.d/iptables save

5.2. mod_auth_kerb Example

This section contains instructions for a basic example for configuring Kerberos authentication with JBoss Core Services' Apache HTTP Server and mod_auth_kerb on Red Hat Enterprise Linux.

5.2.1. mod_auth_kerb Example Prerequisites

The following is a list of prerequisites for the working example. Ensure that all prerequisites are met before attempting to use the example instructions.

  • Install curl with GSS-negotiated support (for testing the configuration).
  • Configure and run a Kerberos or LDAP server (for example ApacheDS) on the same host as JBoss Core Services.
  • If using an LDAP server, create the following LDAP users:

    • Create the user krbtgt:

      dn: uid=krbtgt,ou=Users,dc=example,dc=com
      objectClass: top
      objectClass: person
      objectClass: inetOrgPerson
      objectClass: krb5principal
      objectClass: krb5kdcentry
      cn: KDC Service
      sn: Service
      uid: krbtgt
      userPassword: secret
      krb5PrincipalName: krbtgt/EXAMPLE.COM@EXAMPLE.COM
      krb5KeyVersionNumber: 0
    • Create the user ldap:

      dn: uid=ldap,ou=Users,dc=example,dc=com
      objectClass: top
      objectClass: person
      objectClass: inetOrgPerson
      objectClass: krb5principal
      objectClass: krb5kdcentry
      cn: LDAP
      sn: Service
      uid: ldap
      userPassword: randall
      krb5PrincipalName: ldap/localhost@EXAMPLE.COM
      krb5KeyVersionNumber: 0
    • Create the user HTTP:

      dn: uid=HTTP,ou=Users,dc=example,dc=com
      objectClass: top
      objectClass: person
      objectClass: inetOrgPerson
      objectClass: krb5principal
      objectClass: krb5kdcentry
      cn: HTTP
      sn: Service
      uid: HTTP
      userPassword: secretpwd
      krb5PrincipalName: HTTP/localhost@EXAMPLE.COM
      krb5KeyVersionNumber: 0
    • Create user hnelson (test user):

      dn: uid=hnelson,ou=Users,dc=example,dc=com
      objectClass: top
      objectClass: person
      objectClass: inetOrgPerson
      objectClass: krb5principal
      objectClass: krb5kdcentry
      cn: Horatio Nelson
      sn: Nelson
      uid: hnelson
      userPassword: secret
      krb5PrincipalName: hnelson@EXAMPLE.COM
      krb5KeyVersionNumber: 0

5.2.2. Configure the Kerberos Client

  1. Create the krb5.conf configuration file in the /etc directory, and add the following to the file:

    [logging]
      default = FILE:/var/log/krb5libs.log
      kdc = FILE:/var/log/krb5kdc.log
      admin_server = FILE:/var/log/kadmind.log
    
    [libdefaults]
      default_realm = EXAMPLE.COM
      default_tgs_enctypes = des-cbc-md5,des3-cbc-sha1-kd
      default_tkt_enctypes = des-cbc-md5,des3-cbc-sha1-kd
      dns_lookup_realm = false
      dns_lookup_kdc = false
      allow_weak_crypto = yes
      ticket_lifetime = 24h
      renew_lifetime = 7d
      forwardable = yes
    
    [realms]
      EXAMPLE.COM = {
        kdc = localhost:60088
        admin_server = localhost:60088
      }
    
    [domain_realm]
      .example.com = EXAMPLE.COM
      example.com = EXAMPLE.COM
  2. Create a key tab in the JBCS_HOME/httpd/conf folder with the following contents:

    # ktutil
    ktutil: addent -password -p HTTP/localhost@EXAMPLE.COM -k 0 -e des-cbc-md5
    Password for HTTP/localhost@EXAMPLE.COM: secretpwd
    ktutil: list
    slot KVNO Principal
    ---- ---- ---------------------------------------------------------------------
       1    0               HTTP/localhost@EXAMPLE.COM
    ktutil: wkt JBCS_HOME/httpd/conf/krb5.keytab
    ktutil: quit
Important

Environment variables are not expanded within the ktutil prompt. Users will need to substitute the full path for the JBCS_HOME variable.

As the root user, run the following commands to apply the correct group and permissions to the key tab:

# chgrp apache JBCS_HOME/httpd/conf/krb5.keytab
# chmod 640 JBCS_HOME/httpd/conf/krb5.keytab
  1. Ensure that the following host configuration is included in the /etc/hosts file:

    127.0.0.1 localhost

5.2.3. Configure mod_auth_kerb

Create the auth_kerb.conf configuration file in the JBCS_HOME/httpd/conf.d/ folder, and add the following configuration to the file:

#
# The mod_auth_kerb module implements Kerberos authentication over HTTP, following the "Negotiate" protocol.
#

# The LoadModule statement is done in conf.d/10-auth_kerb.conf
# LoadModule auth_kerb_module modules/mod_auth_kerb.so

<Location /kerberostest>
  AuthType Kerberos
  AuthName "Kerberos Login"
  KrbMethodNegotiate On
  KrbMethodK5Passwd Off
  KrbAuthRealms EXAMPLE.COM
  KrbServiceName HTTP
  Krb5KeyTab $JBCS_HOME/httpd/krb5.keytab
  require valid-user
</Location>
Important

Environment variables are not expanded within the configuration files. Users will need to substitute the full path for the JBCS_HOME variable.

5.2.4. Test the Kerberos Authentication

  1. Create a test page named auth_kerb_page.html in JBCS_HOME/httpd/www/html/kerberostest/.
  2. Add the following contents to the test page (auth_kerb_page.html):

    <html>
    <body>
        <h1>mod_auth_kerb successfully authenticated!</h1>
    </body>
    </html>
  3. Optional: Set the log level for debugging in JBCS_HOME/httpd/conf/httpd.conf.
  4. Start Apache HTTP Server. See the Installation Guide for details.
  5. Test the authentication as follows:

    1. Initiate Kerberos authentication for the test user hnelson:

      $ kinit hnelson
    2. View the details for the test user hnelson:

      $ klist

      A result similar to the following appears:

      Ticket cache: FILE:/tmp/krb5cc_18602
      Default principal: hnelson@EXAMPLE.COM
      
      Valid starting     Expires            Service principal
      06/03/13 14:21:13  06/04/13 14:21:13  krbtgt/EXAMPLE.COM@EXAMPLE.COM
      renew until 06/10/13 14:21:13
    3. Test Apache HTTP Server Kerberos authentication as follows:

      $ curl --negotiate -u : http://localhost/kerberostest/auth_kerb_page.html

      If it is working correctly, the following result appears:

      <html>
      <body>
          <h1>mod_auth_kerb successfully authenticated!</h1>
      </body>
      </html>

See http://modauthkerb.sourceforge.net/ for more information about mod_auth_kerb.