WSO2 MB - System Administration Guide

Contents

1.0 Introduction
2.0 Document Conventions
3.0 Getting WSO2 MB
4.0 Installing and Running WSO2 MB
4.1 Running the MB in Standalone Mode
4.2 Running MB Samples
6.0 Using the WSO2 MB Management Console
7.0 User Management
8.0 Setting Up Logging
9.0 Configuring the Underlying Axis2 Engine
10.0 Adding External Dependencies to the System
11.0 Registry Integration
11.1 Using the Embedded Registry
11.2 Using a Remote Registry
12.0 Setting Up Key Stores
13.0 Setting Up Host Names and Ports

1.0 Introduction

WSO2 MB is an open source Message Broker solution.It is to be your Message Broker System. Our ultimate goal is to provide you a reliable Message Brokering System

WSO2 MB is based on the revolutionary WSO2 Carbon framework. WSO2 Carbon is an OSGi based middleware framework for SOA. Currently all WSO2 Java products are based on WSO2 Carbon including WSO2 Governance Registry and WSO2 WSAS. Since MB is OSGi based some knowledge in OSGi would be helpful in administrating the WSO2 MB.

This document explains how to get WSO2 MB and install it on a server. The latter sections of the document illustrates how to setup and configure various features of the WSO2 MB.

2.0 Document Conventions

  • The phrase 'MB_HOME' refers to the directory in the file system where WSO2 MB is installed
  • The phrase 'MB_SRC_HOME' refers to the directory in the file system where WSO2 MB source distribution is installed
  • All file paths follow Unix/Linux conventions but they resemble Windows file paths as well

3.0 Getting WSO2 MB

Binary distributions and source distributions of WSO2 MB can be downloaded free from the WSO2 MB project home page in the WSO2 Oxygen Tank. Before proceeding to the downloads page you will be asked to register on the WSO2 Oxygen Tank. Registration is free and optional however it is recommended that you sign up for an account right away since registered Oxygen Tank users get exclusive access to our support forums and tons of valuable content related to SOA and Web Services.

Once you are on the downloads page click on the relevant links to download a binary distribution or a source distribution of the alpha release of the WSO2 MB.

If you downloaded a source distribution of the MB you need to build the source to get the executable binary. WSO2 MB uses an Apache Maven2 based build system and therefore you need to first download and install Apache Maven2. Please refer Maven2 documentation on installing and configuring Apache Maven2. Also note that Apache Maven2 requires Java to run. Once Maven2 is properly configured extract the downloaded source distribution and change your working directory to the directory that is created. Then execute the command mvn clean install to run the builder. Once the build process is complete you can find the binary distribution archive in MB_SRC_HOME/modules/distribution/target directory.

4.0 Installing and Running WSO2 MB

To install the WSO2 MB simply extract the downloaded binary distribution archive. If you built WSO2 MB from source extract the archive created by the builder. We recommend installing WSO2 MB on a Unix/Linux system since that will enable you to get the maximum out of the MB. In order to be able to start WSO2 MB you first need Java 6 or higher. Having installed Java on your system please set the JAVA_HOME environment variable to point to the directory in which Java is installed.

4.1 Running WSO2 MB in Standalone Mode

Now you are all set to start WSO2 MB in the standalone mode. Go to MB_HOME/bin directory and if you are on Unix/Linux execute the wso2server.sh shell script or if you are on Windows execute the wso2server.bat batch file. This will start the MB and you can see the progress of the startup procedure on the console. Please note that server startup may take some time depending on the hardware configuration of your system. The first time startup can take up few additional seconds since some first time configuration logic is run by the MB. If the server started up cleanly you should get an output similar to the following on the console.

[2011-02-07 16:18:14,748]  INFO {org.wso2.carbon.server.Main} -  Initializing system...
[2011-02-07 16:18:15,121]  INFO {org.wso2.carbon.server.TomcatCarbonWebappDeployer} -  Deployed Carbon webapp: StandardEngine[carbonEngine].StandardHost[defaulthost].StandardContext[/]
[2011-02-07 16:18:20,721]  INFO {org.wso2.carbon.core.internal.CarbonCoreActivator} -  Starting WSO2 Carbon...
[2011-02-07 16:18:20,744]  INFO {org.wso2.carbon.core.internal.CarbonCoreActivator} -  Operating System : Linux 2.6.32-27-generic, i386
[2011-02-07 16:18:20,744]  INFO {org.wso2.carbon.core.internal.CarbonCoreActivator} -  Java Home        : /opt/softwares/jdk1.6.0_17/jre
[2011-02-07 16:18:20,744]  INFO {org.wso2.carbon.core.internal.CarbonCoreActivator} -  Java Version     : 1.6.0_17
[2011-02-07 16:18:20,744]  INFO {org.wso2.carbon.core.internal.CarbonCoreActivator} -  Java VM          : Java HotSpot(TM) Server VM 14.3-b01,Sun Microsystems Inc.
[2011-02-07 16:18:20,744]  INFO {org.wso2.carbon.core.internal.CarbonCoreActivator} -  Carbon Home      : /home/shammi/wso2/checkouts/carbon-trunk/carbon/products/mb/modules/distribution/target/wso2mb-1.0.0-SNAPSHOT
[2011-02-07 16:18:20,744]  INFO {org.wso2.carbon.core.internal.CarbonCoreActivator} -  Java Temp Dir    : /home/shammi/wso2/checkouts/carbon-trunk/carbon/products/mb/modules/distribution/target/wso2mb-1.0.0-SNAPSHOT/tmp
[2011-02-07 16:18:20,744]  INFO {org.wso2.carbon.core.internal.CarbonCoreActivator} -  User             : shammi, en-US, Asia/Colombo
[2011-02-07 16:18:25,531]  INFO {org.wso2.carbon.registry.core.internal.RegistryCoreServiceComponent} -  Registry Mode    : READ-WRITE
[2011-02-07 16:18:26,833]  INFO {org.apache.qpid.wso2.internal.QpidBundleActivator} -  Setting BundleContext in PluginManager
[Broker] BRK-1006 : Using configuration : /home/shammi/wso2/checkouts/carbon-trunk/carbon/products/mb/modules/distribution/target/wso2mb-1.0.0-SNAPSHOT/repository/conf/qpid/etc/config.xml
Logging configuration error: unable to read file /home/shammi/wso2/checkouts/carbon-trunk/carbon/products/mb/modules/distribution/target/wso2mb-1.0.0-SNAPSHOT/repository/conf/qpid/etc/log4j.xml
Using the fallback internal log4j.properties configuration
[2011-02-07 16:18:26,976]  INFO {org.apache.qpid.server.registry.ApplicationRegistry} -  Initialising Application Registry(org.apache.qpid.server.registry.ConfigurationFileApplicationRegistry@1adff28):1
[2011-02-07 16:18:27,008]  INFO {org.apache.qpid.server.plugins.PluginManager} -  Opened service trackers
[2011-02-07 16:18:27,022]  INFO {org.apache.qpid.server.configuration.plugins.ConfigurationPlugin} -  Elements to lookup:
[2011-02-07 16:18:27,022]  INFO {org.apache.qpid.server.configuration.plugins.ConfigurationPlugin} -  Tag:'queue'
[2011-02-07 16:18:27,022]  INFO {org.apache.qpid.server.configuration.plugins.ConfigurationPlugin} -  Tag:'virtualhosts'
[2011-02-07 16:18:27,027]  INFO {org.apache.qpid.server.configuration.plugins.ConfigurationPlugin} -  Tag:'com'
[2011-02-07 16:18:27,027]  INFO {org.apache.qpid.server.configuration.plugins.ConfigurationPlugin} -  Tag:'common'
[2011-02-07 16:18:27,027]  INFO {org.apache.qpid.server.configuration.plugins.ConfigurationPlugin} -  Tag:'catalina'
[2011-02-07 16:18:27,027]  INFO {org.apache.qpid.server.configuration.plugins.ConfigurationPlugin} -  Tag:'package'
[2011-02-07 16:18:27,027]  INFO {org.apache.qpid.server.configuration.plugins.ConfigurationPlugin} -  Tag:'QPID_HOME'
[2011-02-07 16:18:27,027]  INFO {org.apache.qpid.server.configuration.plugins.ConfigurationPlugin} -  Tag:'line'
[2011-02-07 16:18:27,027]  INFO {org.apache.qpid.server.configuration.plugins.ConfigurationPlugin} -  Tag:'cache-directory'
[2011-02-07 16:18:27,027]  INFO {org.apache.qpid.server.configuration.plugins.ConfigurationPlugin} -  Tag:'security'
[2011-02-07 16:18:27,027]  INFO {org.apache.qpid.server.configuration.plugins.ConfigurationPlugin} -  Tag:'conf'
[2011-02-07 16:18:27,028]  INFO {org.apache.qpid.server.configuration.plugins.ConfigurationPlugin} -  Tag:'osgi'
[2011-02-07 16:18:27,028]  INFO {org.apache.qpid.server.configuration.plugins.ConfigurationPlugin} -  Tag:'wso2'
[2011-02-07 16:18:27,028]  INFO {org.apache.qpid.server.configuration.plugins.ConfigurationPlugin} -  Tag:'sun'
[2011-02-07 16:18:27,028]  INFO {org.apache.qpid.server.configuration.plugins.ConfigurationPlugin} -  Tag:'tomcat'
[2011-02-07 16:18:27,028]  INFO {org.apache.qpid.server.configuration.plugins.ConfigurationPlugin} -  Tag:'javax'
[2011-02-07 16:18:27,028]  INFO {org.apache.qpid.server.configuration.plugins.ConfigurationPlugin} -  Tag:'carbon'
[2011-02-07 16:18:27,028]  INFO {org.apache.qpid.server.configuration.plugins.ConfigurationPlugin} -  Tag:'file'
[2011-02-07 16:18:27,028]  INFO {org.apache.qpid.server.configuration.plugins.ConfigurationPlugin} -  Tag:'advanced'
[2011-02-07 16:18:27,028]  INFO {org.apache.qpid.server.configuration.plugins.ConfigurationPlugin} -  Tag:'path'
[2011-02-07 16:18:27,029]  INFO {org.apache.qpid.server.configuration.plugins.ConfigurationPlugin} -  Tag:'plugin-directory'
[2011-02-07 16:18:27,029]  INFO {org.apache.qpid.server.configuration.plugins.ConfigurationPlugin} -  Tag:'work'
[2011-02-07 16:18:27,029]  INFO {org.apache.qpid.server.configuration.plugins.ConfigurationPlugin} -  Tag:'shared'
[2011-02-07 16:18:27,029]  INFO {org.apache.qpid.server.configuration.plugins.ConfigurationPlugin} -  Tag:'os'
[2011-02-07 16:18:27,029]  INFO {org.apache.qpid.server.configuration.plugins.ConfigurationPlugin} -  Tag:'impl'
[2011-02-07 16:18:27,029]  INFO {org.apache.qpid.server.configuration.plugins.ConfigurationPlugin} -  Tag:'status-updates'
[2011-02-07 16:18:27,029]  INFO {org.apache.qpid.server.configuration.plugins.ConfigurationPlugin} -  Tag:'axis2'
[2011-02-07 16:18:27,029]  INFO {org.apache.qpid.server.configuration.plugins.ConfigurationPlugin} -  Tag:'heartbeat'
[2011-02-07 16:18:27,030]  INFO {org.apache.qpid.server.configuration.plugins.ConfigurationPlugin} -  Tag:'prefix'
[2011-02-07 16:18:27,030]  INFO {org.apache.qpid.server.configuration.plugins.ConfigurationPlugin} -  Tag:'wso2carbon'
[2011-02-07 16:18:27,030]  INFO {org.apache.qpid.server.configuration.plugins.ConfigurationPlugin} -  Tag:'connector'
[2011-02-07 16:18:27,030]  INFO {org.apache.qpid.server.configuration.plugins.ConfigurationPlugin} -  Tag:'java'
[2011-02-07 16:18:27,030]  INFO {org.apache.qpid.server.configuration.plugins.ConfigurationPlugin} -  Tag:'server'
[2011-02-07 16:18:27,030]  INFO {org.apache.qpid.server.configuration.plugins.ConfigurationPlugin} -  Tag:'components'
[2011-02-07 16:18:27,030]  INFO {org.apache.qpid.server.configuration.plugins.ConfigurationPlugin} -  Tag:'management'
[2011-02-07 16:18:27,030]  INFO {org.apache.qpid.server.configuration.plugins.ConfigurationPlugin} -  Tag:'user'
[2011-02-07 16:18:27,038]  INFO {org.apache.qpid.server.configuration.plugins.ConfigurationPlugin} -  Tag:'amqj'
[2011-02-07 16:18:27,038]  INFO {org.apache.qpid.server.configuration.plugins.ConfigurationPlugin} -  Tag:'log4j'
[2011-02-07 16:18:27,042]  INFO {org.apache.qpid.server.configuration.plugins.ConfigurationPlugin} -  Elements to lookup:security
[2011-02-07 16:18:27,042]  INFO {org.apache.qpid.server.configuration.plugins.ConfigurationPlugin} -  Tag:'msg-auth'
[2011-02-07 16:18:27,042]  INFO {org.apache.qpid.server.configuration.plugins.ConfigurationPlugin} -  Tag:'principal-databases'
[2011-02-07 16:18:27,042]  INFO {org.apache.qpid.server.configuration.plugins.ConfigurationPlugin} -  Tag:'jmx'
[2011-02-07 16:18:27,047]  INFO {org.apache.qpid.server.configuration.plugins.ConfigurationPlugin} -  Elements to lookup:security.principal-databases
[2011-02-07 16:18:27,047]  INFO {org.apache.qpid.server.configuration.plugins.ConfigurationPlugin} -  Tag:'principal-database'
[2011-02-07 16:18:27,047]  INFO {org.apache.qpid.server.configuration.plugins.ConfigurationPlugin} -  Elements to lookup:security.jmx
[2011-02-07 16:18:27,047]  INFO {org.apache.qpid.server.configuration.plugins.ConfigurationPlugin} -  Tag:'principal-database'
[2011-02-07 16:18:27,047]  INFO {org.apache.qpid.server.configuration.plugins.ConfigurationPlugin} -  Tag:'access'
[Broker] BRK-1001 : Startup : Version: 0.9 Build: 1041962M
[2011-02-07 16:18:27,163]  INFO {qpid.message.broker.startup} -  [Broker] BRK-1001 : Startup : Version: 0.9 Build: 1041962M
[2011-02-07 16:18:27,166]  INFO {org.apache.qpid.server.management.JMXManagedObjectRegistry} -  Initialising managed object registry using platform MBean server
[2011-02-07 16:18:27,173]  INFO {org.apache.qpid.server.security.auth.database.ConfigurationFilePrincipalDatabaseManager} -  Initialising PrincipalDatabase authentication manager
[2011-02-07 16:18:27,177]  INFO {org.apache.qpid.server.security.auth.database.ConfigurationFilePrincipalDatabaseManager} -  Initialised principal database 'carbon-user-store' successfully
[2011-02-07 16:18:27,178]  INFO {org.apache.qpid.server.security.auth.manager.PrincipalDatabaseAuthenticationManager} -  Initialising Default PrincipalDatabase authentication manager.
[2011-02-07 16:18:27,179]  INFO {org.apache.qpid.server.security.auth.manager.PrincipalDatabaseAuthenticationManager} -  Initialised PLAIN SASL provider successfully
[2011-02-07 16:18:27,211]  INFO {org.apache.qpid.server.security.auth.manager.PrincipalDatabaseAuthenticationManager} -  Additional SASL providers successfully registered.
[Broker] MNG-1001 : Startup
[2011-02-07 16:18:27,243]  INFO {qpid.message.managementconsole.startup} -  [Broker] MNG-1001 : Startup
[Broker] MNG-1004 : Ready : Using the platform JMX Agent
[2011-02-07 16:18:27,244]  INFO {qpid.message.managementconsole.ready} -  [Broker] MNG-1004 : Ready : Using the platform JMX Agent
[2011-02-07 16:18:27,249]  INFO {qpid.message.virtualhost.created} -  [Broker] VHT-1001 : Created : carbon
[2011-02-07 16:18:27,290]  INFO {qpid.message.exchange.created} -  [Broker] EXH-1001 : Create : Durable Type: headers Name: amq.match
[2011-02-07 16:18:27,295]  INFO {qpid.message.exchange.created} -  [Broker] EXH-1001 : Create : Durable Type: topic Name: amq.topic
[2011-02-07 16:18:27,297]  INFO {qpid.message.exchange.created} -  [Broker] EXH-1001 : Create : Durable Type: direct Name: amq.direct
[2011-02-07 16:18:27,299]  INFO {qpid.message.exchange.created} -  [Broker] EXH-1001 : Create : Durable Type: fanout Name: amq.fanout
[2011-02-07 16:18:27,302]  INFO {qpid.message.exchange.created} -  [Broker] EXH-1001 : Create : Durable Type: direct Name: default
[2011-02-07 16:18:27,309]  INFO {qpid.message.exchange.created} -  [Broker] EXH-1001 : Create : Durable Type: direct Name: carbon.direct
[2011-02-07 16:18:27,310]  INFO {qpid.message.exchange.created} -  [Broker] EXH-1001 : Create : Type: topic Name: carbon.topic
[2011-02-07 16:18:27,322]  INFO {qpid.message.configstore.created} -  [Broker] [vh(/carbon)/ms(DerbyMessageStore)] CFG-1001 : Created : org.apache.qpid.server.store.DerbyMessageStore
[2011-02-07 16:18:27,510]  INFO {qpid.message.messagestore.store_location} -  [Broker] [vh(/carbon)/ms(DerbyMessageStore)] MST-1002 : Store location : /home/shammi/wso2/checkouts/carbon-trunk/carbon/products/mb/modules/distribution/target/wso2mb-1.0.0-SNAPSHOT/repository/database/qpid/derbystore
[2011-02-07 16:18:29,360]  INFO {qpid.message.messagestore.recovery_start} -  [Broker] [vh(/carbon)/ms(DerbyMessageStore)] MST-1004 : Recovery Start
[2011-02-07 16:18:29,362]  INFO {qpid.message.transactionlog.recovery_start} -  [Broker] [vh(/carbon)/ms(DerbyMessageStore)] TXN-1004 : Recovery Start
[2011-02-07 16:18:29,381]  INFO {org.apache.qpid.server.store.DerbyMessageStore} -  Recovering bindings...
[2011-02-07 16:18:29,399]  INFO {qpid.message.messagestore.created} -  [Broker] [vh(/carbon)/ms(DerbyMessageStore)] MST-1001 : Created : org.apache.qpid.server.store.DerbyMessageStore
[2011-02-07 16:18:29,406]  INFO {qpid.message.transactionlog.created} -  [Broker] [vh(/carbon)/ms(DerbyMessageStore)] TXN-1001 : Created : org.apache.qpid.server.store.DerbyMessageStore
[2011-02-07 16:18:29,415]  INFO {qpid.message.transactionlog.recovery_complete} -  [Broker] [vh(/carbon)/ms(DerbyMessageStore)] TXN-1006 : Recovery Complete
[2011-02-07 16:18:29,416]  INFO {org.apache.qpid.server.security.auth.manager.PrincipalDatabaseAuthenticationManager} -  Initialising 'carbon' PrincipalDatabase authentication manager.
[Broker] BRK-1002 : Starting : Listening on TCP port 5672
[2011-02-07 16:18:29,484]  INFO {qpid.message.broker.listening} -  [Broker] BRK-1002 : Starting : Listening on TCP port 5672
[Broker] BRK-1004 : Qpid Broker Ready
[2011-02-07 16:18:29,485]  INFO {qpid.message.broker.ready} -  [Broker] BRK-1004 : Qpid Broker Ready
[2011-02-07 16:18:29,685]  INFO {org.wso2.carbon.messagebox.internal.ds.MessageBoxServiceComponent} -  MessageBoxService bundle is activated successfully
[2011-02-07 16:18:29,686]  INFO {org.wso2.carbon.event.core.internal.builder.EventBrokerBuilderDS} -  Successfully registered the event broker
[2011-02-07 16:18:29,746]  INFO {org.wso2.carbon.core.init.CarbonServerManager} -  Starting Carbon initialization...
[2011-02-07 16:18:29,997]  INFO {org.wso2.carbon.core.init.CarbonServerManager} -  Creating super-tenant Axis2 ConfigurationContext
[2011-02-07 16:18:30,444]  INFO {org.apache.axis2.deployment.ClusterBuilder} -  Clustering has been disabled
[2011-02-07 16:18:30,780]  INFO {org.wso2.carbon.core.deployment.DeploymentInterceptor} -  Deploying Axis2 module: rahas-1.60-wso2v1 {super-tenant}
[2011-02-07 16:18:30,950]  INFO {org.wso2.carbon.core.deployment.DeploymentInterceptor} -  Deploying Axis2 module: wso2xfer-3.20-SNAPSHOT {super-tenant}
[2011-02-07 16:18:31,121]  INFO {org.wso2.carbon.core.deployment.DeploymentInterceptor} -  Deploying Axis2 module: rampart-1.60-wso2v1 {super-tenant}
[2011-02-07 16:18:31,388]  INFO {org.wso2.carbon.core.deployment.DeploymentInterceptor} -  Deploying Axis2 module: addressing-3.20-SNAPSHOT {super-tenant}
[2011-02-07 16:18:31,421]  INFO {org.wso2.carbon.core.deployment.DeploymentInterceptor} -  Deploying Axis2 module: wso2mex-3.20-SNAPSHOT {super-tenant}
[2011-02-07 16:18:31,534]  INFO {org.apache.axis2.transport.tcp.TCPTransportSender} -  TCP Sender started
[2011-02-07 16:18:31,974]  INFO {org.wso2.carbon.core.deployment.DeploymentInterceptor} -  Deploying Axis2 service: version {super-tenant}
[2011-02-07 16:18:32,280]  INFO {org.apache.axis2.deployment.DeploymentEngine} -  Deploying Web service: Version.aar - file:/home/shammi/wso2/checkouts/carbon-trunk/carbon/products/mb/modules/distribution/target/wso2mb-1.0.0-SNAPSHOT/repository/deployment/server/axis2services/Version.aar
[2011-02-07 16:18:32,364]  INFO {org.wso2.carbon.core.init.CarbonServerManager} -  Completed super-tenant Axis2 ConfigurationContext creation in 2.367 sec
[2011-02-07 16:18:32,460]  INFO {org.apache.axis2.deployment.ModuleDeployer} -  Deploying module: addressing-SNAPSHOT - file:/home/shammi/wso2/checkouts/carbon-trunk/carbon/products/mb/modules/distribution/target/wso2mb-1.0.0-SNAPSHOT/repository/deployment/client/modules/addressing-SNAPSHOT.mar
[2011-02-07 16:18:32,464]  INFO {org.apache.axis2.transport.tcp.TCPTransportSender} -  TCP Sender started
[2011-02-07 16:18:33,070]  INFO {org.wso2.carbon.core.deployment.DeploymentInterceptor} -  Deploying Axis2 service: TopicManagerAdminService {super-tenant}
[2011-02-07 16:18:33,550]  INFO {org.apache.axis2.deployment.DeploymentEngine} -  Deploying Web service: org.wso2.carbon.event.admin - 
[2011-02-07 16:18:34,926]  INFO {org.apache.axis2.deployment.DeploymentEngine} -  Deploying Web service: org.wso2.carbon.tryit - 
[2011-02-07 16:18:35,724]  INFO {org.wso2.carbon.core.init.CarbonServerManager} -  Repository       : /home/shammi/wso2/checkouts/carbon-trunk/carbon/products/mb/modules/distribution/target/wso2mb-1.0.0-SNAPSHOT/repository/deployment/server/
[2011-02-07 16:18:35,884]  INFO {org.wso2.carbon.core.internal.permission.update.PermissionUpdater} -  Permission cache updated for tenant 0
[2011-02-07 16:18:35,884]  INFO {org.wso2.carbon.core.init.CarbonServerManager} -  ConfigurationContextService registered in 160ms
[2011-02-07 16:18:35,902]  WARN {org.apache.axis2.engine.ListenerManager} -  ConfigurationContext provided for the ListenerManager initialization is null. ListenerManager will not be initialized
[2011-02-07 16:18:35,902]  INFO {org.wso2.carbon.core.transports.http.HttpsTransportListener} -  HTTPS port       : 9443
[2011-02-07 16:18:35,902]  INFO {org.wso2.carbon.core.transports.http.HttpTransportListener} -  HTTP port        : 9763
[2011-02-07 16:18:37,207]  INFO {org.wso2.carbon.ui.internal.CarbonUIServiceComponent} -  Mgt Console URL  : https://10.100.0.164:9443/carbon/
[2011-02-07 16:18:37,242]  INFO {org.wso2.carbon.core.internal.StartupFinalizerServiceComponent} -  Started Transport Listener Manager
[2011-02-07 16:18:37,242]  INFO {org.wso2.carbon.core.internal.StartupFinalizerServiceComponent} -  Server           :  WSO2 MB -1.0.0-SNAPSHOT
[2011-02-07 16:18:37,242]  INFO {org.wso2.carbon.core.internal.StartupFinalizerServiceComponent} -  WSO2 Carbon started in 21 sec



To verify that the MB is up and running fire off your Web browser and go to https://localhost:9443/carbon. This will take you to the WSO2 MB on-line management console.

Log-in

You can login to the console using the default user credentials given below.

  • Username: admin
  • Password: admin

If you can get that far then the MB is properly installed and running.

WSO2 MB startup scripts stated above accept a few useful arguments.

--cleanRegistry
  This argument forces the embedded Registry instance to be cleaned before starting the MB. Note that this will clean the internal database therefore any configurations you saved previously will be permanently lost.

--restart
   Restart the Carbon Unix daemon.

-debug <port>
   Enables remote debugging on the MB through the specified port.

-dump
   Print a thread dump of the Carbon Unix daemon.

In addition to the above mentioned arguments the MB startup scripts accept the following VM arguments.

-DosgiConsole
   Starts the OSGi console from which you can directly interact with the underlying OSGi runtime.

4.0 WSO2 MB Directory Hierarchy

When you extract a WSO2 MB binary distribution archive you will find the following directories in the top level that is created.

bin -
Contains all the necessary scripts to interact with the WSO2 MB instance. There are shell scripts (with .sh extension) for Unix/Linux users and batch files (with .bat extension) for Windows users. In general you will find the following scripts in this directory.

  • wso2server.sh/wso2server.bat - Launches WSO2 MB
  • wsdl2java.sh/wsdl2java.bat - Launches the Java stub generation tool for Web Services
  • java2wsdl.sh/java2wsdl.bat - Launches the WSDL generation tool for Java Web Services
  • tcpmon.sh/tcpmon.bat - Launches TCPMon, the TCP connection monitor
  • chpasswd.sh/chpasswd.bat -Use this script to change the administrator password without signing in to the server
  • daemon.sh -Start WSO2 MB as a daemon on Unix/Linux systems
  • install.bat - Install WSO2 MB as a background service on Windows
  • repowriter.sh/repowriter.bat

In addition to the above mentioned scripts you will find a sub-directory named 'native' in the bin directory.

repository/deployment -
This directory houses all the OSGi bundles, service artifacts, modules and related resources used by the WSO2 MB instance. The repository/components/plugins directory will contain all the necessary OSGi bundles at server runtime.

repository/conf -
All the global configuration files (eg: axis2.xml, transports-mgt.xml, carbon.xml ) used by the MB are stored in this directory.

lib -
The lib directory houses all the jar files and OSGi bundles required by the embedded Tomcat instance. Starting from Carbon 2.0 the log4j.properties file used by the MB is also stored here.

resources -
Contains additional resources required by WSO2 MB. This includes security related resources such as keystores.

repository/logs -
All the server logs created during server runtime will be stored here.

dbscripts -
Contains a collection of database scripts required to create the Carbon database on a variety of database management systems.

5.0 Using the WSO2 MB Management Console

WSO2 MB management console is a Web based control panel powered by JSP and AJAX which enables system administrators to interact with a running MB instance, without having to touch any underlying configuration files. The management console allows the users to command and control proxy services, sequences, transports, local entries, registry, modules, endpoints and much more. MB management console is a great way to try things out without having to edit the actual configuration files or without having to restart the MB for changes to take effect.

We recommend using Mozilla Firefox 3 or Internet Explorer 7 to access the WSO2 MB management console. Please note that your browser must be JavaScript enabled to take the full advantage of the management console. To access the MB management console fire off you Web browser and navigate to https://<Server Host>:<Server Port>/<Context>. If you are running the Web browser on the same machine as the MB you may use 'localhost' as the server host. The default port and the context for the MB management console are '9443' and 'carbon' respectively. If you entered the URL correctly you will be taken to the management console's login page.

On the login page enter 'admin' as the username and the password to login to the system. You can change user credentials and even add new users once you login. Controls and wizards in the MB management console are pretty much self explanatory. However if you are having trouble finishing your way in the management console, click on the 'Help' link at the top right corner of any page to access context sensitive help.

Please note that the MB management console makes use of the default HTTPS servlet transport which is configured in the MB_HOME/conf/transports.xml file. It is important that this transport is always properly configured in the mentioned file. Otherwise the management console might be inaccessible to the users.

6.0 User Management

To access the WSO2 MB user management features, first sign in to the MB management console and click on 'User Management' under the 'Configure' menu in the left navigation bar. This will take you to the User Management home page which contains the controls illustrated below.

User Mgt

From here you can manage users and roles. A user is associated with zero or more roles (generally specified at user creation time) and each role is associated with zero or more permissions (generally specified at role creation time). Therefore the set of permissions owned by a user is determined by the roles assigned to that user. A user owns the union of all the permissions associated with the roles assigned to that user. By default MB comes with only one role, the 'admin' role. This role is associated with the following set of permissions.

By default the admin user is associated with the admin role and hence the admin user is entitled to all the permissions.

To add a new role to the system click on 'Roles' in the User Management home page and on the page that appears click the 'Add New Role' link. This will start the 'Add Role' wizard. The wizard will guide you though the process of creating a role by specifying a unique name for the role and adding the relevant permissions to the new role. Similarly to create a new user, click on 'Users' in the User Management home page. Then from the next page that appears select 'Create New User' link. This will launch the 'Add User' wizard which will enable you to create a new user account with login credentials and associate the account with one or more existing roles. The MB management console also enables you to search for and modify existing users and roles.

WSO2 MB can be easily configured to use an external user store in addition to the built-in system user store. An external user store is an external database which stores user data. It could be as simple as a relational database or as sophisticated as an LDAP instance. Most organizations maintain such centralized databases and it would be productive from the organization's point of view to have the MB pick up user data from the existing centralized user database. To connect the MB to an external user store simply click on the 'Add External User Store' link on the User Management home page. Then on the page that appears select the type of user store that will be plugged into the MB. Currently the following types of user stores are supported.

  • JDBC
  • LDAP
  • Active Directory

Having selected the type of the user store you need to provide additional information required by the MB to connect to and retrieve user data from the external user store. If all the required parameters were specified accurately the MB will pick up user data from the external user store and users registered on the external store will be able to access the MB as if their accounts were created in the built-in system user store.

7.0 Setting Up Logging

Logging is one of the most important aspects of a production grade server. A properly configured logging system is vital in identifying errors, security threats and usage patterns. WSO2 MB uses a log4j based logging mechanism through Apache Commons Logging facade library. The log4j.properties file which governs how logging is performed by the server can be found in MB_HOME/lib directory. However it is recommended not to make any alterations to the default log4j.properties file. The recommended way of setting up logging is by using the MB management console. Simply login to the management console and click on 'Logging' under the 'Configure' menu in the left navigation bar. From here you can setup various appenders and configure log levels for various loggers. Any changes to the logging configuration you make from the management console will get priority over what is defined in the actual log4j.properties file.

By default WSO2 MB comes with the following log appenders configured.

  • CARBON_CONSOLE (Logs to the console when the server is running)
  • CARBON_LOGFILE (Writes the logs to MB_HOME/logs/wso2-MB.log)
  • CARBON_MEMORY
  • CARBON_SYS_LOG
  • SERVICE_APPENDER (Writes mediation time audit messages to MB_HOME/logs/wso2-MB-service.log)
  • TRACE_APPENDER (Writes mediation time tracing/debug messages to the MB_HOME/logs/wso2-MB-trace.log for tracing enabled services)
  • TRACE_MEMORYAPPENDER

Tracing can be enabled for individual mediation sequences and proxy services from the 'Mediation Sequences' home page and the 'Service Dashboard' page respectively. Click on the 'Sequences' link under 'Mediation' in the 'Manage' menu of the left navigation bar to access the 'Mediation Sequences' page. This page lists all the deployed sequences. Each sequence gives you the options to enable/disable tracing. To access the service dashboard for a proxy service go to the Services List page and click on the proxy service that you are interested in. Once a sequence or a proxy service is tracing enabled you can view the generated log messages by visiting the 'Mediation Tracer' page under the 'Monitor' menu. The 'Monitor' menu also gives you access to the system logs and the SOAP tracer logs all through the Web interface itself.

Logs