JBoss 3.2.1 Config Notes
May 29, 2003
Marty Phelan

==============================================================================
A. Install and Config Software
==============================================================================

1. Software used in this installation:

  a. RedHat Linux 8.0
  b. JDK 1.4.1_02 from Sun (may work with JDK 1.4.1_01 also)
  c. JBoss 3.2.1 with Tomcat 4.1.24

2. IMPORTANT *** After installing JDK set the following variable before using JBoss:

  export LD_PRELOAD=/usr/java/j2sdk1.4.1_02/jre/lib/i386/server/libjsig.so

  (assumes location of JDK install to be /usr/java/j2sdk1.4.1_02)

3. This installation sets up a full JBoss app server with all features enabled,
   including clustering and farming.

4. To start JBoss, use the following commands or create a script file containing:
   (you may need to modify the path's for your environment)

  #!/bin/bash

  export JAVA_HOME=/usr/java/j2sdk1.4.1_02
  export LD_PRELOAD=/usr/java/j2sdk1.4.1_02/jre/lib/i386/server/libjsig.so

  cd /usr/local/jboss-3.2.1_tomcat-4.1.24/bin
  ./run.sh -c all

5. Download and configure sample applications for testing your JBoss installation.
   There is a sample application: MapperLibrary which can be used to test your
   installation. To run the sample application you must do the following:

   a. create an Oracle user and run the table-create and table-data sql scripts.
   b. create the LibraryDS connection (step B below)
   c. create the LibraryTestDomain security domain (step C below)
   d. configure the Mail service (step F below)
   e. deploy the mapperlibrary.ear application into <jboss-dir>/server/all/farm/


==============================================================================
B. Setup Oracle Connection pool(s)
==============================================================================

1. Copy the Oracle driver (e.g. classes12.jar) to <jboss-dir>/server/all/lib/

2. Modify <jboss-dir>/server/all/deploy/transaction-service.xml
   In "Transactions" section find XidFactory mbean and add/uncomment
   "Pad" attribute with value of "true"

  EXAMPLE:

  <!-- The configurable Xid factory.  For use with Oracle, set pad to true -->
  <mbean code="org.jboss.tm.XidFactory"
	 name="jboss:service=XidFactory">
    <attribute name="Pad">true</attribute>
  </mbean>


3. Create a datasource - determine name for datasource(s).

  EXAMPLE:

  Datasource name:     LibraryDS

4. Modify following example and replace "URL", "User", and "Password".
   Save file as <jboss-dir>/server/all/deploy/library-ds.xml
   
   IMPORTANT: The name of the file must end in "-ds.xml" to be recognized as
              a datasource descriptor.

-------------------------------------------------------------------------------
   Example for Library Datasource using Oracle
   (based on <jboss-dir>/docs/examples/jca/oracle-xa-ds.xml)
-------------------------------------------------------------------------------

<?xml version="1.0" encoding="UTF-8"?>

<!-- ===================================================================== -->
<!--                                                                       -->
<!--  Oracle Datasource Configuration                                      -->
<!--                                                                       -->
<!-- ===================================================================== -->

<!-- ===================================================================== -->
<!-- ATTENTION:  DO NOT FORGET TO SET Pad=true IN transaction-service.xml  -->
<!-- ===================================================================== -->

<datasources>
  <xa-datasource>
    <jndi-name>LibraryDS</jndi-name>
    <track-connection-by-tx>true</track-connection-by-tx>
    <isSameRM-override-value>false</isSameRM-override-value>
    <xa-datasource-class>oracle.jdbc.xa.client.OracleXADataSource</xa-datasource-class>
    <xa-datasource-property name="URL">jdbc:oracle:thin:@192.168.5.1:1521:ORCL</xa-datasource-property>
    <xa-datasource-property name="User">librarian</xa-datasource-property>
    <xa-datasource-property name="Password">shelves</xa-datasource-property>
    <exception-sorter-class-name>org.jboss.resource.adapter.jdbc.vendor.OracleExceptionSorter</exception-sorter-class-name>
  </xa-datasource>
</datasources>

-------------------------------------------------------------------------------
   -- END -- Example for Library Datasource using Oracle
-------------------------------------------------------------------------------

==============================================================================
C. Setup "Testing Only" security domain
==============================================================================

This security domain is generally used for testing purposes only. It is not optimized
for production level performance.

1. Modify <jboss-dir>/server/all/conf/login-config.xml and add the following
   section (example):

    <application-policy name="LibraryTestDomain">
      <authentication>
        <login-module code="org.jboss.security.auth.spi.UsersRolesLoginModule"
            flag = "required">
          <module-option name="usersProperties">library.users</module-option>
          <module-option name="rolesProperties">library.roles</module-option>
        </login-module>
      </authentication>
    </application-policy>

2. Create the following files. They can be deployed globally by copying them into
   the <jboss-dir>/server/all/conf/ directory, or they can be deployed with
   your application so they will appear in the classpath (e.g. in a war file in
   the /WEB-INF/classes directory). NOTE: They cannot be deployed BOTH at the
   global level and application level.

  library.users -----------
  # -- These are the special users of the Library System
  librarian=shelves
  frontdesk=books

  library.roles -----------
  # -- These are the special roles for the Library System
  librarian=admin,checkout
  frontdesk=checkout

==============================================================================
D. Setup "Database" security domain
==============================================================================

This security domain uses a database which contains user and role information.

1. Create the following tables and populate them with data:

    create table USER_PRINCIPAL
    (
      USER_NAME VARCHAR2(64) PRIMARY KEY not null,
      PASSWORD VARCHAR2(64)
    );

    create table USER_PRINCIPAL_ROLE
    (
      USER_NAME VARCHAR2(64) not null,
      USER_ROLE VARCHAR2(32) not null,
      CONSTRAINT USER_PRINCIPAL_ROLE_PK PRIMARY KEY (USER_NAME,USER_ROLE)
    );

    insert into USER_PRINCIPAL (USER_NAME,PASSWORD) values ('librarian','shelves');
    insert into USER_PRINCIPAL (USER_NAME,PASSWORD) values ('frontdesk','books');

    insert into USER_PRINCIPAL_ROLE (USER_NAME,USER_ROLE) values ('librarian','admin');
    insert into USER_PRINCIPAL_ROLE (USER_NAME,USER_ROLE) values ('librarian','checkout');
    insert into USER_PRINCIPAL_ROLE (USER_NAME,USER_ROLE) values ('frontdesk','checkout');

2. Make sure there is a datasource defined to access these tables. For this example
   we will use the LibraryDS as defined in section B.

3. Modify <jboss-dir>/server/all/conf/login-config.xml and add the following
   section:

    <application-policy name="LibraryDatabaseDomain">
      <authentication>
        <login-module code="org.jboss.security.auth.spi.DatabaseServerLoginModule" flag="required">
          <module-option name="dsJndiName">java:/LibraryDS</module-option>
          <module-option name="principalsQuery">
            select password from user_principal where user_name=?
          </module-option>
          <module-option name="rolesQuery">
            select user_role, 'Roles' from user_principal_role where user_name=?
          </module-option>
        </login-module>
      </authentication>
    </application-policy>

==============================================================================
E. Setup "LDAP" security domain -- SECTION NOT COMPLETE --
==============================================================================

This security domain uses an LDAP server which contains user and role information.
This example assumes you have an LDAP server up and running with users and roles
or groups setup.

3. Modify <jboss-dir>/server/all/conf/login-config.xml and add the following
   section:

    <application-policy name="jmx-console">
      <authentication>
        <login-module code="org.jboss.security.auth.spi.LdapLoginModule" flag="required">
          <module-option name="java.naming.factory.initial">com.sun.jndi.ldap.LdapCtxFactory</module-option>
          <module-option name="java.naming.provider.url">ldap://pegasus.taursys.com:389/</module-option>
          <module-option name="java.naming.security.authentication">simple</module-option>
          <module-option name="principalDNPrefix">uid=</module-option>
          <module-option name="principalDNSuffix">,ou=People,dc=taursys,dc=com</module-option>
          <module-option name="rolesCtxDN">ou=Group,dc=taursys,dc=com</module-option>
          <module-option name="uidAttributeID">member</module-option>
          <module-option name="roleAttributeID">cn</module-option>
          <module-option name="matchOnUserDN">true</module-option>
          <module-option name="hashAlgorithm">MD5</module-option>
        </login-module>
      </authentication>
    </application-policy>

==============================================================================
F. Configure Mail service
==============================================================================


This will configure the mail connector which can be used by applications running
in the JBoss container. Modify the <jboss-dir>/server/all/deploy/mail-service.xml:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE server>
<server>

  <classpath codebase="lib"
             archives="mail.jar, activation.jar, mail-plugin.jar"/>

  <!-- ==================================================================== -->
  <!-- Mail Connection Factory                                              -->
  <!-- ==================================================================== -->

  <mbean code="org.jboss.mail.MailService"
         name="jboss:service=Mail">
    <attribute name="JNDIName">java:/Mail</attribute>
    <attribute name="User">nobody</attribute>
    <attribute name="Password">password</attribute>
    <attribute name="Configuration">
       <!-- Test -->
       <configuration>
          <!-- Change to your mail server prototocol -->
          <property name="mail.store.protocol" value="pop3"/>
          <property name="mail.transport.protocol" value="smtp"/>

          <!-- Change to the user who will receive mail  -->
          <property name="mail.user" value="mr_jboss@taursys.com"/>

          <!-- Change to the mail server  -->
          <property name="mail.pop3.host" value="klh.taursys.com"/>

          <!-- Change to the SMTP gateway server -->
          <property name="mail.smtp.host" value="klh.taursys.com"/>

          <!-- Change to the address mail will be from  -->
          <property name="mail.from" value="mr_jboss@taursys.com"/>

          <!-- Enable debugging output from the javamail classes -->
          <property name="mail.debug" value="false"/>
       </configuration>
    </attribute>
  </mbean>

</server>

==============================================================================
G. Clustering and Farming
==============================================================================

The "all" configuration of JBoss 3.2.1 has clustering and farming enabled by
default. If your routers/hubs and operating systems are configured to allow
multicast traffic, then additional instances of JBoss servers should see each
other and cluster.

To test multicasting, use the following command:

  ping -b 224.0.0.1
  
The systems which have multicasting available should respond:

  PING 224.0.0.1 (224.0.0.1) from 192.168.5.30 : 56(84) bytes of data.
  64 bytes from 192.168.5.30: icmp_seq=1 ttl=64 time=0.084 ms
  64 bytes from 192.168.5.50: icmp_seq=1 ttl=64 time=0.993 ms (DUP!)
  64 bytes from 192.168.5.30: icmp_seq=2 ttl=64 time=0.071 ms
  64 bytes from 192.168.5.50: icmp_seq=2 ttl=64 time=0.505 ms (DUP!)
  ...

  (you should see yourself in this list as well)