• Replace JBOSS_CONFIG/deploy/jboss-messaging.sar/hsqldb-persistence-service.xml by the persistence-service of from <downloadPackage>/examples/config.

• Configure a JCA datasource using an example from $JBOSS_HOME/docs/examples/jca

  and copying to $JBOSS_CONFIG/deploy

  JBoss Messaging uses DefaultDS by default so you should configure your datasource to bind to that

• Remove hsqldb-ds.xml from $JBOSS_CONFIG/deploy

• Copy your database driver to $JBOSS_CONFIG/lib

  Your database driver can probably be downloaded from your database providers web site

• Move $JBOSS_CONFIG/deploy/jms/jms-ds.xml and $JBOSS_CONFIG/deploy/jms/jms-ra.rar to $JBOSS_CONFIG/deploy

• Remove the old JBoss MQ by removing the directory $JBOSS_CONFIG/deploy/jms.

  .

  Remove the old JBoss MQ jar file: $JBOSS_CONFIG/lib/jbossmq.jar

• Add a security policy called "messaging" on $JBOSS_CONFIG/config/login-config.xml. You could use this as an example, or create one according to JBoss Security Documentation:

  <application-policy name = "messaging">
  <authentication>
  <login-module code = "org.jboss.security.auth.spi.UsersRolesLoginModule" flag = "required" >
     <module-option name = "unauthenticatedIdentity">guest</module-option>
     <module-option name = "usersProperties">props/messaging-users.properties</module-option>
     <module-option name = "rolesProperties">props/messaging-roles.properties</module-option>
  </login-module>
  </authentication>
  </application-policy>
            

  In case you are using the above policy you should also create files messaging-users.properties and messaging-roles.properties in the $JBOSS_CONFIG/config/props/ directory

  .

  Note

  You can find an example messaging-users.properties and messaging-roles.properties in the JBoss Messaging distribution in the <downloadPackage>src/etc/server/default/config directory.

  # messaging-roles.properties
  # Add roles as you like
  # user=role1,role2,...
  #
  guest=guest
            

  # messaging-users.properties
  
  # Add users as you like
  # user=password
  #
  guest=guest
            

• Unzip jboss-messaging.sar from your download package into the directory JBOSS_CONFIG/deploy/jboss-messaging.sar

  JBoss Messaging sar should be deployed unzipped (exploded) so you have easy access to its config files which are stored there.

• Copy jboss-messaging.jar from your download package into the directory JBOSS_CONFIG/lib

  jboss-messaging.jar needs to go in the lib directory so it is accessible to other services e.g. the JBoss Transactions Recovery Manager

• Warning

  For use in production it is highly recommended to use a different database other than the HSQLDB. HSQLDB does not have any transaction isolation. For simple non clustered development evaluation HSQLDB may suffice. If you decide to use a different database please follow the follow steps:

  • Replace JBOSS_CONFIG/deploy/jboss-messaging.sar/hsqldb-persistence-service.xml by the persistence-service of from <downloadPackage>/examples/config.

  • Configure a JCA datasource using an example from $JBOSS_HOME/docs/examples/jca

    and copying to $JBOSS_CONFIG/deploy

    JBoss Messaging uses DefaultDS by default so you should configure your datasource to bind to that

  • Remove hsqldb-ds.xml from $JBOSS_CONFIG/deploy

  • Copy your database driver to $JBOSS_CONFIG/lib

    Your database driver can probably be downloaded from your database providers web site

• There are few extra steps at Section 5.1.5, “Extra steps to complete your installation”

• That's it!

For the rest of the procedure we assume JBOSS_CONFIG refers to your new messaging configuration (e.g. messaging-node0)

You don't actually have to create an environment variable JBOSS_CONFIG, this is just used in the installation instructions to describe the steps

• Set up the JBOSS_HOME environment variable to point to the JBoss 4.2 installation you want to use JBoss Messaging with. Run the installation script, available in the util directory of the release bundle as follows:

   cd util
   ant -f release-admin.xml -Dmessaging.config.source=all -Dmessaging.config.name=messaging-node0
           

  In the above you would substitute messaging-node0 with whatever is the name you want to give the configuration. If you will have several cluster nodes on the same machine, e.g. for development purposes then a good convention is to name them messaging-node0, messaging-node1 to match messaging-node<ServerPeerID>

  The installation script will create a $JBOSS_HOME/server/messaging-node0 configuration. (If you have chosen messaging-node0)

• Warning

  For a clustered installation it is mandatory that a shared database is available to all nodes in the cluster. The default JBoss AS uses HSQLDB for its database which is a local shared database. Therefore in order to use clustering you must replace this with a different shared database. If the database is not replaced then clustering will not work.

  • Replace $JBOSS_CONFIG/deploy/jboss-messaging.sar/hsqldb-persistence-service.xml by the clustered-<databasename>-persistence-service from <downloadPackage>/examples/config.. For instance clustered-mysql-persistence-service.xml

  • Configure a JCA datasource using an example from $JBOSS_HOME/docs/examples/jca

    and copying to $JBOSS_CONFIG/deploy

    JBoss Messaging uses DefaultDS by default so you should configure your datasource to bind to that

  • Remove hsqldb-ds.xml from $JBOSS_CONFIG/deploy

  • Copy your database driver to $JBOSS_CONFIG/lib

    Your database driver can probably be downloaded from your database provider's web site

• Ensure the ServerPeerID MBean constructor parameter in messaging-service.xml is unique for each node on the cluster. The ServerPeerID value must be a valid integer.

  Warning

  Each node must have a unique ServerPeerID for clustering to work!

• If you want to run multiple JBoss Messaging nodes on the same box using the same IP address, e.g. for development purposes, then you can use the ServiceBindingManager to do this as follows:

  • Uncomment binding manager service from $JBOSS_CONFIG/conf/jboss-service.xml

  • Specify the desired port rage (e.g. ports-01, ports-02... etc)

  • Look at $JBOSS_HOME/docs/examples/binding-manager/sample-bindings.xml. On each port range, JBoss Remoting configuration should look like:

          <service-config name="jboss.messaging:service=Connector,transport=bisocket"
                          delegateClass="org.jboss.services.binding.AttributeMappingDelegate">
             <delegate-config>
                <attribute name="Configuration"><![CDATA[
    	   <config>
                <invoker transport="bisocket">
                   <attribute name="marshaller" isParam="true">org.jboss.jms.wireformat.JMSWireFormat</attribute>
                   <attribute name="unmarshaller" isParam="true">org.jboss.jms.wireformat.JMSWireFormat</attribute>
                   <attribute name="dataType" isParam="true">jms</attribute>
                   <attribute name="socket.check_connection" isParam="true">false</attribute>
                   <attribute name="timeout" isParam="true">0</attribute>
                   <attribute name="serverBindAddress">${jboss.bind.address}</attribute>
                   <attribute name="serverBindPort">4657</attribute>
                   <attribute name="leasePeriod">10000</attribute>
                   <attribute name="clientSocketClass" isParam="true">org.jboss.jms.client.remoting.ClientSocketWrapper</attribute>
                   <attribute name="serverSocketClass">org.jboss.jms.server.remoting.ServerSocketWrapper</attribute>
                   <attribute name="numberOfRetries" isParam="true">1</attribute>
                   <attribute name="numberOfCallRetries" isParam="true">1</attribute>
                   <attribute name="clientMaxPoolSize" isParam="true">50</attribute>
                </invoker>
                <handlers>
                   <handler subsystem="JMS">org.jboss.jms.server.remoting.JMSServerInvocationHandler</handler>
                </handlers>
             </config>
                ]]></attribute>
             </delegate-config>
             <binding port="4657"/>
          </service-config>
                  
                  

    Warning

    You must ensure that the config (like above) is identical to that in remoting-service.xml With the exception of the actual serverBindPort which clearly must be different for each ports range. Please note that the default JBoss Messaging service binding manager bindings in sample-bindings.xml shipped with JBAS 4.2.0 is out of date and you will need to copy the config from remoting-service.xml

    You should ensure that each node is configured to use a different ports range.

• There are few extra steps at Section 5.1.5, “Extra steps to complete your installation”

• That's it

• Move $JBOSS_CONFIG/deploy/jms/hajndi-jms-ds.xml and $JBOSS_CONFIG/deploy/jms/jms-ra.rar to $JBOSS_CONFIG/deploy

• Remove the old JBoss MQ by removing the directory $JBOSS_CONFIG/deploy/jms.

  .

  Remove the old JBoss MQ jar file: $JBOSS_CONFIG/lib/jbossmq.jar

  Make sure you don't have any JBossMQ files under $JBOSS_CONFIG/deploy-hasingleton. For that just remove $JBOSS_CONFIG/deploy-hasingleton/jms

• Add a security policy called "messaging" on $JBOSS_CONFIG/config/login-config.xml. You could use this as an example, or create one according to JBoss Security Documentation:

  <application-policy name = "messaging">
  <authentication>
  <login-module code = "org.jboss.security.auth.spi.UsersRolesLoginModule" flag = "required" >
     <module-option name = "unauthenticatedIdentity">guest</module-option>
     <module-option name = "usersProperties">props/messaging-users.properties</module-option>
     <module-option name = "rolesProperties">props/messaging-roles.properties</module-option>
  </login-module>
  </authentication>
  </application-policy>
            

  In case you are using the above policy you should also create files messaging-users.properties and messaging-roles.properties in the $JBOSS_CONFIG/config/props/ directory

  .

  Note

  You can find an example messaging-users.properties and messaging-roles.properties in the JBoss Messaging distribution in the <downloadPackage>src/etc/server/default/config directory.

  # messaging-roles.properties
  # Add roles as you like
  # user=role1,role2,...
  #
  guest=guest
            

  # messaging-users.properties
  
  # Add users as you like
  # user=password
  #
  guest=guest
            

• Unzip jboss-messaging.sar from your download package into the directory JBOSS_CONFIG/deploy/jboss-messaging.sar

  JBoss Messaging should be deployed unzipped (exploded) so you have easy access to its config files which are stored there.

• Copy jboss-messaging.jar from your download package into the directory JBOSS_CONFIG/lib

  jboss-messaging.jar needs to go in the lib directory so it is accessible to other services e.g. the JBoss Transactions Recovery Manager

• Warning

  For a clustered installation it is mandatory that a shared database is available to all nodes in the cluster. The default JBoss AS uses HSQLDB for its database which is a local shared database. Therefore in order to use clustering you must replace this with a different shared database. If the database is not replaced then clustering will not work.

  • Replace $JBOSS_CONFIG/deploy/jboss-messaging.sar/hsqldb-persistence-service.xml by the clustered-<databasename>-persistence-service from <downloadPackage>/examples/config.. For instance clustered-mysql-persistence-service.xml

  • Configure a JCA datasource using an example from $JBOSS_HOME/docs/examples/jca

    and copying to $JBOSS_CONFIG/deploy

    JBoss Messaging uses DefaultDS by default so you should configure your datasource to bind to that

  • Remove hsqldb-ds.xml from $JBOSS_CONFIG/deploy

  • Copy your database driver to $JBOSS_CONFIG/lib

    Your database driver can probably be downloaded from your database provider's web site

• Ensure the ServerPeerID MBean constructor parameter in messaging-service.xml is unique for each node on the cluster. The ServerPeerID value must be a valid integer.

  Warning

  Each node must have a unique ServerPeerID for clustering to work!

• If you want to run multiple JBoss Messaging nodes on the same box using the same IP address, e.g. for development purposes, then you can use the ServiceBindingManager to do this as follows:

  • Uncomment binding manager service from $JBOSS_CONFIG/conf/jboss-service.xml

  • Specify the desired port rage (e.g. ports-01, ports-02... etc)

  • Look at $JBOSS_HOME/docs/examples/binding-manager/sample-bindings.xml. On each port range, JBoss Remoting configuration should look like:

          <service-config name="jboss.messaging:service=Connector,transport=bisocket"
                          delegateClass="org.jboss.services.binding.AttributeMappingDelegate">
             <delegate-config>
                <attribute name="Configuration"><![CDATA[
    	   <config>
                <invoker transport="bisocket">
                   <attribute name="marshaller" isParam="true">org.jboss.jms.wireformat.JMSWireFormat</attribute>
                   <attribute name="unmarshaller" isParam="true">org.jboss.jms.wireformat.JMSWireFormat</attribute>
                   <attribute name="dataType" isParam="true">jms</attribute>
                   <attribute name="socket.check_connection" isParam="true">false</attribute>
                   <attribute name="timeout" isParam="true">0</attribute>
                   <attribute name="serverBindAddress">${jboss.bind.address}</attribute>
                   <attribute name="serverBindPort">4657</attribute>
                   <attribute name="leasePeriod">10000</attribute>
                   <attribute name="clientSocketClass" isParam="true">org.jboss.jms.client.remoting.ClientSocketWrapper</attribute>
                   <attribute name="serverSocketClass">org.jboss.jms.server.remoting.ServerSocketWrapper</attribute>
                   <attribute name="numberOfRetries" isParam="true">1</attribute>
                   <attribute name="numberOfCallRetries" isParam="true">1</attribute>
                   <attribute name="clientMaxPoolSize" isParam="true">50</attribute>
                </invoker>
                <handlers>
                   <handler subsystem="JMS">org.jboss.jms.server.remoting.JMSServerInvocationHandler</handler>
                </handlers>
             </config>
                ]]></attribute>
             </delegate-config>
             <binding port="4657"/>
          </service-config>
                  
                  

    Warning

    You must ensure that the config (like above) is identical to that in remoting-service.xml With the exception of the actual serverBindPort which clearly must be different for each ports range. Please note that the default JBoss Messaging service binding manager bindings in sample-bindings.xml shipped with JBAS 4.2.0 is out of date and you will need to copy the config from remoting-service.xml

    You should ensure that each node is configured to use a different ports range.

• There are few extra steps at Section 5.1.5, “Extra steps to complete your installation”

• That's it

• Edit $JBOSS_CONFIG/jms-ds.xml and replace jboss.mq by jboss.messaging on every occurrence

  If you are in a clustered installation, then do the above with the file $JBOSS_CONFIG/hajndi-jms-ds.xml

• Edit $JBOSS_CONFIG/config/standardjboss.xml and set CreateJBossMQDestination to false on every occurrence

  Make sure it looks like this:

  <CreateJBossMQDestination>false</CreateJBossMQDestination>

  Those Proxies will try to create a Destination on JBossMQ if they can't find it on JNDI, what would cause some errors related to JBoss MQ.

• Edit $JBOSS_CONFIG/config/jboss-service.xml and remove the reference to JBoss MQ on JSR-77 Management Bean:

   <!-- ==================================================================== -->
   <!-- JSR-77 Single JBoss Server Management Domain                         -->
   <!-- ==================================================================== -->
   <mbean code="org.jboss.management.j2ee.LocalJBossServerDomain"
  
    ... Remove this line ...
   <attribute name="JMSService">jboss.mq:service=DestinationManager</attribute>
               

• Change $JBOSS_CONFIG/conf/login-config.xml and remove jboss-mq security policies

  ### Remove these lines:
  
  <!-- Security domain for JBossMQ -->
  <application-policy name = "jbossmq">
   <authentication>
      <login-module code = "org.jboss.security.auth.spi.DatabaseServerLoginModule"
         flag = "required">
         <module-option name = "unauthenticatedIdentity">guest</module-option>
         <module-option name = "dsJndiName">java:/DefaultDS</module-option>
         <module-option name = "principalsQuery">
               SELECT PASSWD FROM JMS_USERS WHERE USERID=?</module-option>
         <module-option name = "rolesQuery">
               SELECT ROLEID, 'Roles' FROM JMS_ROLES WHERE USERID=?</module-option>
      </login-module>
   </authentication>
  </application-policy>
  
  <!-- Security domain for JBossMQ when using file-state-service.xml
  <application-policy name = "jbossmq">
   <authentication>
      <login-module code = "org.jboss.mq.sm.file.DynamicLoginModule"
         flag = "required">
         <module-option name = "unauthenticatedIdentity">guest</module-option>
         <module-option name = "sm.objectname">jboss.mq:service=StateManager</module-option>
      </login-module>
   </authentication>
  </application-policy>
  -->