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

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:

  If you want to create a simple non clustered installion based on the default configuration:

           cd util
           ant -f release-admin.xml
           

  If you want to create a clustered installation based on the all configuration or change the configuration name:

   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 want 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 messaging.config.source variable determines which JBoss AS configuration (e.g. default or all) to base the installation on

  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 databasename>-persistence-service from <downloadPackage>/examples/config.. For instance 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 attribute value in messaging-service.xml is unique for each node. The ServerPeerID value must be a valid integer. Every node MUST have a unique id, including those just connected by message bridges.

  Warning

  Each node must have a unique ServerPeerID irrespective of whether you are using clustering.

• 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. Here is an example:

          <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">
                
                   <!-- There should be no reason to change these parameters - warning!
                        Changing them may stop JBoss Messaging working correctly -->            
                   <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="clientSocketClass" isParam="true">org.jboss.jms.client.remoting.ClientSocketWrapper</attribute>
                   <attribute name="serverSocketClass" isParam="true">org.jboss.jms.server.remoting.ServerSocketWrapper</attribute>
                   <attribute name="numberOfCallRetries" isParam="true">1</attribute>
                   <attribute name="pingFrequency" isParam="true">214748364</attribute>
                   <attribute name="pingWindowFactor" isParam="true">10</attribute>
                   <attribute name="onewayThreadPool">org.jboss.jms.server.remoting.DirectThreadPool</attribute>
                   
                   <!-- Periodicity of client pings. Server window by default is twice this figure -->                               
                   <attribute name="clientLeasePeriod" isParam="true">10000</attribute>
    
                   <!-- Number of seconds to wait for a connection in the client pool to become free -->
                   <attribute name="numberOfRetries" isParam="true">10</attribute>
    
                   <!-- Max Number of connections in client pool. This should be significantly higher than
                        the max number of sessions/consumers you expect -->
                   <attribute name="JBM_clientMaxPoolSize" isParam="true">200</attribute>
                   
                   <!-- Use these parameters to specify values for binding and connecting control connections to 
                        work with your firewall/NAT configuration
                   <attribute name="secondaryBindPort">xyz</attribute>                           
                   <attribute name="secondaryConnectPort">abc</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-bisocket-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 may be out of date and you will need to copy the config from remoting-bisocket-service.xml. DO NOT just copy and paste from the above example - copy it from the JBoss Messaging distribution.

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

• There are few extra steps at Section 4.1.3, “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 databasename>-persistence-service from <downloadPackage>/examples/config.. For instance 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 attribute value 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 irrespective of whether you are using clustering.

• 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">
                
                   <!-- There should be no reason to change these parameters - warning!
                        Changing them may stop JBoss Messaging working correctly -->            
                   <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="clientSocketClass" isParam="true">org.jboss.jms.client.remoting.ClientSocketWrapper</attribute>
                   <attribute name="serverSocketClass" isParam="true">org.jboss.jms.server.remoting.ServerSocketWrapper</attribute>
                   <attribute name="numberOfCallRetries" isParam="true">1</attribute>
                   <attribute name="pingFrequency" isParam="true">214748364</attribute>
                   <attribute name="pingWindowFactor" isParam="true">10</attribute>
                   <attribute name="onewayThreadPool">org.jboss.jms.server.remoting.DirectThreadPool</attribute>
                   
                   <!-- Periodicity of client pings. Server window by default is twice this figure -->                               
                   <attribute name="clientLeasePeriod" isParam="true">10000</attribute>
    
                   <!-- Number of seconds to wait for a connection in the client pool to become free -->
                   <attribute name="numberOfRetries" isParam="true">10</attribute>
    
                   <!-- Max Number of connections in client pool. This should be significantly higher than
                        the max number of sessions/consumers you expect -->
                   <attribute name="JBM_clientMaxPoolSize" isParam="true">200</attribute>
                   
                   <!-- Use these parameters to specify values for binding and connecting control connections to 
                        work with your firewall/NAT configuration
                   <attribute name="secondaryBindPort">xyz</attribute>                           
                   <attribute name="secondaryConnectPort">abc</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-bisocket-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 may be out of date and you will need to copy the config from remoting-bisocket-service.xml. DO NOT just copy and paste from the above example - copy it from the JBoss Messaging distribution.

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

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

• That's it

You should also make these changes on any configuration you choose, to remove all references to the old JBossMQ:

• Warning

  SECURITY RISK! To avoid a security risk, you MUST specify the value of the attribute SuckerPassword in the Server Peer config (messaging-service.xml). If you do not specify a value, the default value will be used. Any person that knows the default value will be able to access to all destinations on the server. The password chosen should only be exposed to administrators

• Note

  JBoss Messaging 1.4.0 requires a patched version of jboss-remoting.jar. This version is available on JBoss EAP 4.3, so if you're using a different version of JBoss you should download the patched version which can be found hereThe version is JBoss Remoting 2.2.2.SP4-brew. Please download it and copy it into the $JBOSS_HOME/server/<your server name>/lib directory of any server profiles that use JBoss Messaging 1.4.0. If you are using JBoss Messaging from a standalone client also make sure this jar is on your classpath *before* jbossall-client.jar.

• Edit $JBOSS_CONFIG/deploy/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/deploy/hajndi-jms-ds.xml

• Edit $JBOSS_CONFIG/conf/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/conf/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>
  -->