Overview
Downloads
Documentation
- Installation Guide
- User Guide
- Administrator Guide
Samples
Resources
Community
Project Info
1.0 Introduction
2.0 Document Conventions
3.0 Getting WSO2 CEP
4.0 Installing and Running WSO2 CEP
4.1 Running the CEP in Standalone Mode
4.2 Running CEP Samples
6.0 Using the WSO2 CEP 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
WSO2 CEP is an open source CEP solution.It is to be your Complex Event Processing System. Our ultimate goal is to provide you with the suitable capability of analyzing , filtering and triggering events according to your organization's decisions.
WSO2 CEP 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 CEP is OSGi based some knowledge in OSGi would be helpful in administrating the WSO2 CEP.
This document explains how to get WSO2 CEP and install it on a server. The latter sections of the document illustrates how to setup and configure various features of the WSO2 CEP.
Binary distributions and source distributions of WSO2 CEP can be downloaded free from the WSO2 CEP 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 1.0.0 release of the WSO2 CEP.
If you downloaded a source distribution of the CEP you need to build the source to get the executable binary. WSO2 CEP 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 CEP_SRC_HOME/modules/distribution/target directory.
To install the WSO2 CEP simply extract the downloaded binary distribution archive. If you built WSO2 CEP from source extract the archive created by the builder. We recommend installing WSO2 CEP on a Unix/Linux system since that will enable you to get the maximum out of the CEP. In order to be able to start WSO2 CEP 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.
Now you are all set to start WSO2 CEP in the standalone mode. Go to CEP_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 CEP Server 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 CEP. If the server started up cleanly you should get an output similar to the following on the console.
[2010-12-22 18:46:52,069] INFO {org.wso2.carbon.server.Main} - Initializing system...
[2010-12-22 18:46:52,308] INFO {org.wso2.carbon.server.TomcatCarbonWebappDeployer} - Deployed Carbon webapp: StandardEngine[carbonEngine].StandardHost[defaulthost].StandardContext[/]
[2010-12-22 18:46:57,303] INFO {org.wso2.carbon.core.internal.CarbonCoreActivator} - Starting WSO2 Carbon...
[2010-12-22 18:46:57,326] INFO {org.wso2.carbon.core.internal.CarbonCoreActivator} - Operating System : Linux 2.6.32-26-generic, i386
[2010-12-22 18:46:57,326] INFO {org.wso2.carbon.core.internal.CarbonCoreActivator} - Java Home : /opt/softwares/jdk1.6.0_17/jre
[2010-12-22 18:46:57,326] INFO {org.wso2.carbon.core.internal.CarbonCoreActivator} - Java Version : 1.6.0_17
[2010-12-22 18:46:57,326] INFO {org.wso2.carbon.core.internal.CarbonCoreActivator} - Java VM : Java HotSpot(TM) Server VM 14.3-b01,Sun Microsystems Inc.
[2010-12-22 18:46:57,326] INFO {org.wso2.carbon.core.internal.CarbonCoreActivator} - Carbon Home : /home/shammi/wso2/checkouts/carbon-branch-3.1.0/products/cep/modules/distribution/target/wso2cep-1.0.0
[2010-12-22 18:46:57,326] INFO {org.wso2.carbon.core.internal.CarbonCoreActivator} - Java Temp Dir : /home/shammi/wso2/checkouts/carbon-branch-3.1.0/products/cep/modules/distribution/target/wso2cep-1.0.0/tmp
[2010-12-22 18:46:57,326] INFO {org.wso2.carbon.core.internal.CarbonCoreActivator} - User : shammi, en-US, Asia/Colombo
[2010-12-22 18:47:01,208] INFO {org.wso2.carbon.registry.core.internal.RegistryCoreServiceComponent} - Registry Mode : READ-WRITE
[2010-12-22 18:47:01,238] INFO {org.wso2.carbon.brokermanager.core.internal.build.BrokerManagerServiceBuilder} - The broker-manager-config.xml can not found
[2010-12-22 18:47:02,319] INFO {org.wso2.carbon.brokermanager.core.internal.ds.BrokerManagerDS} - Successfully deployed the broker manager service
[2010-12-22 18:47:02,615] INFO {org.wso2.carbon.core.init.CarbonServerManager} - Starting Carbon initialization...
[2010-12-22 18:47:02,757] INFO {org.wso2.carbon.core.init.CarbonServerManager} - Creating super-tenant Axis2 ConfigurationContext
[2010-12-22 18:47:02,939] INFO {org.apache.axis2.deployment.ClusterBuilder} - Clustering has been disabled
[2010-12-22 18:47:03,076] INFO {org.wso2.carbon.core.deployment.DeploymentInterceptor} - Deploying Axis2 module: rampart-1.60-wso2v1 {super-tenant}
[2010-12-22 18:47:03,120] INFO {org.wso2.carbon.core.deployment.DeploymentInterceptor} - Deploying Axis2 module: wso2mex-3.10 {super-tenant}
[2010-12-22 18:47:03,170] INFO {org.wso2.carbon.core.deployment.DeploymentInterceptor} - Deploying Axis2 module: addressing-3.10 {super-tenant}
[2010-12-22 18:47:03,235] INFO {org.wso2.carbon.core.deployment.DeploymentInterceptor} - Deploying Axis2 module: rahas-1.60-wso2v1 {super-tenant}
[2010-12-22 18:47:03,274] INFO {org.wso2.carbon.core.deployment.DeploymentInterceptor} - Deploying Axis2 module: sandesha2-3.10 {super-tenant}
[2010-12-22 18:47:03,294] INFO {org.wso2.carbon.core.deployment.DeploymentInterceptor} - Deploying Axis2 module: wso2xfer-3.10 {super-tenant}
[2010-12-22 18:47:03,314] INFO {org.wso2.carbon.core.deployment.DeploymentInterceptor} - Deploying Axis2 module: wso2caching-3.10 {super-tenant}
[2010-12-22 18:47:03,333] INFO {org.wso2.carbon.core.deployment.DeploymentInterceptor} - Deploying Axis2 module: wso2throttle-3.10 {super-tenant}
[2010-12-22 18:47:03,439] INFO {org.apache.axis2.transport.tcp.TCPTransportSender} - TCP Sender started
[2010-12-22 18:47:03,648] INFO {org.wso2.carbon.core.deployment.DeploymentInterceptor} - Deploying Axis2 service: version {super-tenant}
[2010-12-22 18:47:03,795] INFO {org.apache.axis2.deployment.DeploymentEngine} - Deploying Web service: Version.aar - file:/home/shammi/wso2/checkouts/carbon-branch-3.1.0/products/cep/modules/distribution/target/wso2cep-1.0.0/repository/deployment/server/axis2services/Version.aar
[2010-12-22 18:47:03,905] INFO {org.wso2.carbon.core.init.CarbonServerManager} - Completed super-tenant Axis2 ConfigurationContext creation in 1.148 sec
[2010-12-22 18:47:04,071] INFO {org.apache.axis2.deployment.ModuleDeployer} - Deploying module: rampart-1.5 - file:/home/shammi/wso2/checkouts/carbon-branch-3.1.0/products/cep/modules/distribution/target/wso2cep-1.0.0/repository/deployment/client/modules/rampart-1.5.mar
[2010-12-22 18:47:04,086] INFO {org.apache.axis2.deployment.ModuleDeployer} - Deploying module: addressing-1.6-wso2v3 - file:/home/shammi/wso2/checkouts/carbon-branch-3.1.0/products/cep/modules/distribution/target/wso2cep-1.0.0/repository/deployment/client/modules/addressing-1.6-wso2v3.mar
[2010-12-22 18:47:04,091] INFO {org.apache.axis2.transport.tcp.TCPTransportSender} - TCP Sender started
[2010-12-22 18:47:04,421] INFO {org.wso2.carbon.core.deployment.DeploymentInterceptor} - Deploying Axis2 service: BrokerManagerAdminService {super-tenant}
[2010-12-22 18:47:04,794] INFO {org.apache.axis2.deployment.DeploymentEngine} - Deploying Web service: org.wso2.carbon.brokermanager.admin -
[2010-12-22 18:47:05,120] INFO {org.wso2.carbon.core.deployment.DeploymentInterceptor} - Deploying Axis2 service: CEPAdminService {super-tenant}
[2010-12-22 18:47:05,817] INFO {org.apache.axis2.deployment.DeploymentEngine} - Deploying Web service: org.wso2.carbon.cep.admin -
[2010-12-22 18:47:07,640] INFO {org.apache.axis2.deployment.DeploymentEngine} - Deploying Web service: org.wso2.carbon.tryit -
[2010-12-22 18:47:08,108] INFO {org.wso2.carbon.core.init.CarbonServerManager} - Repository : /home/shammi/wso2/checkouts/carbon-branch-3.1.0/products/cep/modules/distribution/target/wso2cep-1.0.0/repository/deployment/server/
[2010-12-22 18:47:08,132] INFO {org.wso2.carbon.event.broker.subscriptions.EmbeddedRegistryBasedSubscriptionManager} - Connection established with the registry
[2010-12-22 18:47:08,139] INFO {org.wso2.carbon.broker.core.BrokerService} - The broker.xml can not found
[2010-12-22 18:47:08,139] INFO {org.wso2.carbon.broker.core.BrokerService} - No broker types are given
[2010-12-22 18:47:08,353] INFO {org.wso2.carbon.cep.core.internal.ds.CEPServiceDS} - Successfully deployed the cep service
[2010-12-22 18:47:08,353] INFO {org.wso2.carbon.broker.core.internal.ds.BrokerServiceDS} - Successfully deployed the broker service
[2010-12-22 18:47:08,379] INFO {org.wso2.carbon.core.internal.permission.update.PermissionUpdater} - Permission cache updated for tenant 0
[2010-12-22 18:47:08,380] INFO {org.wso2.carbon.core.init.CarbonServerManager} - ConfigurationContextService registered in 272ms
[2010-12-22 18:47:08,386] INFO {org.wso2.carbon.core.transports.http.HttpsTransportListener} - HTTPS port : 9443
[2010-12-22 18:47:08,386] INFO {org.wso2.carbon.core.transports.http.HttpTransportListener} - HTTP port : 9763
[2010-12-22 18:47:10,033] INFO {org.wso2.carbon.ui.internal.CarbonUIServiceComponent} - Mgt Console URL : https://10.100.0.127:9443/carbon/
[2010-12-22 18:47:10,080] INFO {org.wso2.carbon.core.internal.StartupFinalizerServiceComponent} - Started Transport Listener Manager
[2010-12-22 18:47:10,080] INFO {org.wso2.carbon.core.internal.StartupFinalizerServiceComponent} - Server : WSO2 CEP-1.0.0
[2010-12-22 18:47:10,080] INFO {org.wso2.carbon.core.internal.StartupFinalizerServiceComponent} - WSO2 Carbon started in 17 sec
To verify that the CEP is up and running fire off your Web browser and go to https://localhost:9443/carbon. This will take you to the WSO2 CEP on-line management console.
You can login to the console using the default user credentials given below.
If you can get that far then the CEP is properly installed and running.
WSO2 CEP startup scripts stated above accept a few useful arguments.
--cleanRegistry
This argument forces the embedded Registry instance to be cleaned before
starting the CEP. 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 CEP through the specified port.
-dump
Print a thread dump of the Carbon Unix daemon.
In addition to the above mentioned arguments the CEP startup scripts accept the following VM arguments.
-DosgiConsole
Starts the OSGi console from which you can directly interact with the
underlying OSGi runtime.
WSO2 CEP ships with a set of sample configurations which enables you to get familiar with the product quickly and easily. Please refer the WSO2 CEP samples guide for sample configuration and details on how to run them.
When you extract a WSO2 CEP 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 CEP 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.
repository/deployment -
This directory houses all the OSGi bundles, service artifacts, modules and
related resources used by the WSO2 CEP 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 CEP 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 CEP is also stored here.
resources -
Contains additional resources required by WSO2 CEP. 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.
WSO2 CEP management console is a Web based control panel powered by JSP and AJAX which enables system administrators to interact with a running CEP 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. CEP management console is a great way to try things out without having to edit the actual configuration files or without having to restart the CEP for changes to take effect.
We recommend using Mozilla Firefox 3 or Internet Explorer 7 to access the WSO2 CEP management console. Please note that your browser must be JavaScript enabled to take the full advantage of the management console. To access the CEP 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 CEP you may use 'localhost' as the server host. The default port and the context for the CEP 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 CEP 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 CEP management console makes use of the default HTTPS servlet transport which is configured in the CEP_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.
To access the WSO2 CEP user management features, first sign in to the CEP 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.
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 CEP comes with only one role, the 'admin' role. This role is associated with the following set of permissions. (In fact all the CEP related permissions are listed here, meaning that users with admin role gets all the permissions over the system)
By default the admin user is associated with the admin role and hence the admin user is entitled to all the above 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 CEP management console also enables you to search for and modify existing users and roles.
WSO2 CEP 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 CEP pick up user data from the existing centralized user database. To connect the CEP 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 CEP. Currently the following types of user stores are supported.
Having selected the type of the user store you need to provide additional information required by the CEP to connect to and retrieve user data from the external user store. If all the required parameters were specified accurately the CEP will pick up user data from the external user store and users registered on the external store will be able to access the CEP as if their accounts were created in the built-in system user store.
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 CEP 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 CEP_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 CEP 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 CEP comes with the following log appenders configured.
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.
