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

    .

    If you are installing in a clustered configuration make sure to set the Clustered attribute to true

  • 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:

  Warning

  JBoss5 has introduced a much simpler ServiceBindingManager. You should refer to the JBoss5 documentation about how to administer the new bindingManager if you are using JBoss5.

  • 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

    The above config only apply to JBoss 4.2 and EAP 4.3. On EAP4.3 and JBOSS 4.2 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.. On JBoss5 the ports are controlled by system-property substitution hence you don't need to worry about copying the config into bindings.xml

    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

    If you are installing in a clustered configuration make sure to set the Clustered attribute to true

  • 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.4 requires pecific versions of jboss-remoting.jar. If you are installing JBoss Messaging with JBoss 4.2+, you should use this version: Remoting 2.2.3. If you are using EAP you don't need to take any extra steps on the remoting installation.

• 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>
  -->
               
              

• Copy the jbossmq.jar from the Source Machine(JBossMQ) under the server/default/lib/ to the messaging configuration on the Target JBM machine(server/messaging/lib)

  Note

  substitute what ever your messaging server configuration is above. I used the default stand alone messaging server configuration note: This is required to dereference the JBossMQ objects that are dereferenced on the JBM side. If you don't copy the jar over, you will get a "java.lang.ClassCastException: javax.naming.Reference" exception and the bridge will not be able to start

• Add the remote JBossMQ provider to the jms-ds.xml file in the server/messaging/deploy directory on your target(JBM) machine.

  Here is an example of the provider to add.

  <mbean code="org.jboss.jms.jndi.JMSProviderLoader"
                 name="jboss.messaging:service=JMSProviderLoader,
                 name=MyRemoteJMSProvider">
    <attribute name="ProviderName">RemoteXAConnectionFactory</attribute>
    <attribute name="ProviderAdapterClass">org.jboss.jms.jndi.JNDIProviderAdapter</attribute>
    <!-- The combined connection factory -->
    <attribute name="FactoryRef">XAConnectionFactory</attribute>
    <!-- The queue connection factory -->
    <attribute name="QueueFactoryRef">XAConnectionFactory</attribute>
    <!-- The topic factory -->
    <attribute name="TopicFactoryRef">XAConnectionFactory</attribute>
    <attribute name="Properties">
       java.naming.factory.initial=org.jnp.interfaces.NamingContextFactory
       java.naming.factory.url.pkgs=org.jboss.naming:org.jnp.interfaces
       java.naming.provider.url=192.168.0.199:1099
    </attribute>
  </mbean>
              

  Note

  you will need to change the java.naming.provider.url so that it points to your JBossMQ machine. Everything else should remain the same. Keep your jms-ds.xml file open, because you will be addning another entry in it for the next step.

• Add the Bridge provider to the jms-ds.xml file in the server/messaging/deploy directory on your target(JBM) machine.

  Here is an example bridge configuration

  <mbean code="org.jboss.jms.server.bridge.BridgeService"
                    name="jboss.messaging:service=Bridge,name=TestBridge"
                    xmbean-dd="xmdesc/Bridge-xmbean.xml">
       <depends optional-attribute-name="SourceProviderLoader">
                    jboss.messaging:service=JMSProviderLoader,
                    name=MyRemoteJMSProvider</depends>
       <depends optional-attribute-name="TargetProviderLoader">
                    jboss.messaging:service=JMSProviderLoader,
                    name=JMSProvider</depends>
       <attribute name="SourceDestinationLookup">/queue/testQueue</attribute>
       <attribute name="TargetDestinationLookup">/queue/A</attribute>
       <attribute name="QualityOfServiceMode">0</attribute>
       <attribute name="MaxBatchSize">5</attribute>
       <attribute name="MaxBatchTime">-1</attribute>
       <attribute name="FailureRetryInterval">5000</attribute>
       <attribute name="MaxRetries">-1</attribute>
       <attribute name="AddMessageIDInHeader">false</attribute>
  </mbean>
                 

  Note

  my target is the current JBM JMS Provider and the source is the JBossMQ remote provider. If you have a pretty stock system and you want to move messages from JBossMQ to JBM, you will not have to change this example except for the queue Names. If you wish to move from JBM to JBossMQ, just switch the soure and target definitions.