You are on page 1of 116

WSO2 Carbon 4.1.

Carbon
Documentation
Version 4.1.0
WSO2 Carbon 4.1.0

Table of Contents
1. Setting Up the Environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
2. WSO2 Carbon Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
2.1 About WSO2 Carbon . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
2.1.1 Introducing Carbon . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
2.1.2 Carbon Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
2.1.3 Carbon Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
2.1.4 Getting Help . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
2.1.5 About this Release . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
2.2 Installation Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
2.2.1 Downloading the Product . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
2.2.2 Installation Prerequisites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
2.2.3 Installing the Product . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
2.2.3.1 Installing on Linux . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
2.2.3.2 Installing on Solaris . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
2.2.3.3 Installing on Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
2.2.3.4 Installing as a Windows Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
2.2.3.5 Installing as a Linux Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
2.2.4 Running the Product . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
2.2.5 Introducing the Management Console . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
2.3 User Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
2.3.1 User Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
2.3.1.1 Introduction to User Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
2.3.1.2 Users and Roles Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
2.3.1.2.1 Adding and Deleting Users . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
2.3.1.2.2 Changing the Current User's Password . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
2.3.1.2.3 Resetting a User's Password . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
2.3.1.2.4 Adding and Deleting User Roles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
2.3.1.3 Configuring User Stores . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
2.3.1.3.1 Realm Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
2.3.1.3.2 Changing the RDBMS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
2.3.1.3.3 Default JDBC User Store Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
2.3.1.3.4 Default LDAP User Store Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
2.3.1.3.5 Configuring External User Stores . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
2.3.2 Feature Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
2.3.2.1 Introduction to Feature Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
2.3.2.2 Managing the Feature Repository . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
2.3.2.3 Installing Features via the UI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
2.3.2.4 Installed Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
2.3.2.5 Installation History . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
2.3.3 Server Roles for cApps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67
2.3.3.1 Introduction to Server Roles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68
2.3.3.2 Adding a Server Role . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69
2.3.3.3 Deleting a Server Role . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70
2.3.4 Transport Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70
2.3.4.1 Introduction to Transports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71

Copyright WSO2 Inc. 2005-2014 2


WSO2 Carbon 4.1.0

2.3.4.2 Carbon Transports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71


2.3.4.2.1 HTTP Servlet Transport . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71
2.3.4.2.2 HTTPS Servlet Transport . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75
2.3.4.2.3 HTTP-NIO Transport . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75
2.3.4.2.4 HTTPS-NIO Transport . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77
2.3.4.2.5 VFS Transport . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78
2.3.4.2.6 JMS Transport . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
2.3.4.2.7 MailTo Transport . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
2.3.4.2.8 TCP Transport . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
2.3.4.2.9 Local Transport . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86
2.3.4.2.10 UDP Transport . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86
2.3.4.2.11 FIX Transport . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
2.4 Tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89
2.4.1 Capturing the State of the System in Error Situations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90
2.4.2 Changing User Passwords in the Carbon Database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90
2.4.3 Encrypting and Decrypting Simple Texts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91
2.4.4 View and Resend Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92
2.4.5 WSO2 Carbon Secure Vault . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96
2.5 Developer Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100
2.5.1 Building from Source . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101
2.5.2 Creating a Carbon Kernel Patch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102
2.5.3 Shipping a Kernel Patch with Distribution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107
2.5.4 Applying a Patch to the Kernel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109
2.5.5 Adding External Libraries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109
2.6 Reference Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110
2.6.1 Default Ports of WSO2 Products . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111
2.7 Getting Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114
2.8 Site Map . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115

Copyright WSO2 Inc. 2005-2014 3


WSO2 Carbon 4.1.0

Setting Up the Environment


1. Build the product from the source.
For more information please see, Building from Source.
2. Setup the environment using one of the following commands:
If you are using Eclipse use the following command:

mvn eclipse:eclipse

If you are using intelliJIDEA use the following command:

mvn idea:idea

Copyright WSO2 Inc. 2005-2014 4


WSO2 Carbon 4.1.0

WSO2 Carbon Documentation


Welcome to WSO2 Carbon 4.1.0 Documentation! WSO2 Carbon is the award-winning, light-weight, service-oriented
platform for all WSO2 products. It is 100% open source and is delivered under Apache License 2.0. Consisting of a
collection of OSGi bundles, WSO2 Carbon hosts components for integration, security, clustering, governance,
statistics, and other features in the middleware space.
This documentation provides information on setting up, configuring and implementing WSO2 Carbon. It is structured
by topics most frequently searched for by users. For a comprehensive, end-to-end coverage of the entire product, its
important subject areas, and the advanced configurations, we recommend that you follow the defined order of
topics.

About WSO2 Carbon Installation Guide User Guide

The topics in this section Instructions to download, install Explores in-depth the features
introduce WSO2 Carbon, and run WSO2 Carbon. and functionality of WSO2
including the business cases it Carbon, configuration, testing,
solves, its features, and debugging and deployment.
architecture.

Tools Developer Guide

This section is useful when This section has useful


troubleshooting Carbon based developer information such as
products. information on Carbon Kernel
patching and adding external
libraries.

Copyright WSO2 Inc. 2005-2014 5


WSO2 Carbon 4.1.0

About WSO2 Carbon


The topics in this section introduce you to WSO2 Carbon, the business cases it solves, its features, architecture,
release information, and how to get help on any issues or queries you might have.
Introducing Carbon
Carbon Features
Carbon Architecture
Getting Help
About this Release

Introducing Carbon
WSO2 Carbon is the award-winning, component-based, service oriented platform for the enterprise-grade WSO2
middleware products stack. It is 100% open source and delivered under Apache License 2.0. The WSO2 Carbon
platform is lean, high-performant and consists of a collection of OSGi bundles.
The WSO2 Carbon core platform hosts a rich set of middleware components encompassing capabilities such as
security, clustering, logging, statistics, management and more. These are basic features required by all WSO2
products, which are developed on top of the base platform.
All WSO2 products are a collection of Carbon components. They have been developed simply by plugging various
Carbon components which provide different features. The WSO2 Carbon Component Manager provides capability
to extend the Carbon base platform by selecting the components which address your unique requirements and
installing them with point-and-click simplicity. Therefore, by provisioning this innovative base platform, you can
develop your own, lean middleware product which has remarkable flexibility to change as business requirements
change.

About WSO2 Carbon Installation User Guide

The topics in this section Instructions to download, install Explores in-depth the features
introduce WSO2 Carbon, and run WSO2 Carbon. and functionality of WSO2
including the business cases it Carbon, configuration, testing,
solves, its features, and debugging and deployment.
architecture.

Tools Developer Guide

This section is useful when This section has useful


troubleshooting Carbon based developer information such as
products. information on Carbon Kernel
patching and adding external
libraries.

Carbon Features

Feature Description

Copyright WSO2 Inc. 2005-2014 6


WSO2 Carbon 4.1.0

Core SOA Features Mechanisms to provide and consume services, message mediation, service
orchestration, service governance, business process management and service
monitoring.
Extensive support for enterprise integration patterns.
Support for industry standards such as WS-*, REST and other binary and
non-binary protocols.
In-built Quality of Service (QoS) capabilities such as security, reliable messaging,
and throttling.
Clear separation of UI components and internal framework which manages
deployment artifacts, allowing clear separation of concerns, better memory
utilization and improved security.

Extensible and Because of its OSGi-based architecture, WSO2 Carbon (or any Carbon-based
Future-Proof product) is easily extensible on-the-fly, in a simple, point-and-click deployment.
Start with a lean core and click to install only what is needed.
Choose from more than 200 (and growing) features to plug in functionality as and
when new business needs demand.
Clean separation of functionality with minimum dependency for a rich SOA model.
Equinox P2 provisioning automatically identifies dependencies and installs them for
you.
Flexibility to deploy other OSGi bundles from existing open source projects to
custom-coded OSGi components.

Flawless Deployment Same code base in both standalone mode of WSO2 Carbon (as well as all
Flexibility Carbon-based products) and in private and public cloud deployments.
Create multi-tenant-aware applications via the Carbon API without worrying about
underlying complexities.

Quality of Service Supports highly-available deployments.


Features Horizontal scaling via clustering with stateless server architecture.
Dynamic discovery of services using WS-Discovery.
Lazy loading via ghost deployers.
Apache Zookeeper based co-ordination support.

Synchronizing Apache Subversion (SVN) based Deployment Synchronizer to manage the


Deployment Artifacts deployment artifacts for both products and services.
Additionally supports WSO2 Governance Registry as a repository.
Large number of server artifacts can be deployed easily in one go.

Complete User Supports authentication and role-based authorization.


Management Supports pluggable heterogeneous user stores such as LDAP, Active Directory, and
Capability JDBC, using custom extension points.

Governance Registry Govern and monitor large-scale deployments, including clustered servers and cloud
Integration implementations.
Applied across the entire WSO2 Carbon middleware platform.

Distributed Caching Supports the standard J-cache AP.


Tested and proven in distributed environments for boosted performance.

Lightweight, GUI, command-line and IDE-based tools for artifact generation, development and
Developer-Friendly and testing.
Easy-to-Deploy Integrated to WSO2 Developer Studio, the Eclipse-based IDE.
User-friendly management console.
Server customization via feature provisioning.
Choice of deployment to on-premise servers, private or public cloud.
Integrated with SVN, Maven, Ant and other standard tools.

Copyright WSO2 Inc. 2005-2014 7


WSO2 Carbon 4.1.0

Carbon Architecture
WSO2 Carbon is based on Java OSGi technology, which allows components to be dynamically installed, started,
stopped, updated, and uninstalled while eliminating component version conflicts. In Carbon, this capability translates
into a solid core of common middleware components useful across any enterprise project, plus the ability to add
components for specific features needed to solve a specific enterprise scenario.

The core set of components in WSO2 Carbon provide WSO2 middleware products with enterprise-class
management, security, clustering, logging, statistics, tracing, throttling, caching, and other capabilities as well as a
management UI framework. Central to these components is WSO2s solid and high performance SOA and Web
Services engine. Add-in components encapsulate different functionality.
A unified graphical management console can deploy, manage, and view services, processes, process instances,
and statistics across the whole platform, comprising of different products. As each runtime component is added,
associated management components are added to the UI. With a clean front-end/back-end separation between the
UI and the runtime, all capabilities can be controlled through a remote WSO2 Carbon UI, or through a clean Web
Services interface.

Copyright WSO2 Inc. 2005-2014 8


WSO2 Carbon 4.1.0

We use Carbon as the core of our middleware products reflecting familiar middleware product categories. Most
users will start with one of these categories with the assurance that components can be added/removed to facilitate
changing business requirements.

Getting Help
In addition to this documentation, there are several ways to get help as you work on WSO2 products.

Explore learning resources

For tutorials, articles, whitepapers, webinars, and other learning resources, look in the 'Resources' menu on the WS
O2 website. In products that have a visual user interface, click the Help link in the top right-hand corner to get help
with your current task.

Try our support options

WSO2 offers a variety of development and production support programs, ranging from web-based support during
normal business hours to premium 24x7 phone support. WSO2 is committed to ensuring that your enterprise
middleware deployment is completely supported from evaluation to production. Our unique approach ensures that
support leverages the open development methodology and is provided by the very same engineers who build the
products.
For additional support information, see http://wso2.com/support.

Ask questions

Ask questions and find solutions in the user forums at http://stackoverflow.com. Ensure that you tag your question
with appropriate keywords such as WSO2 and Carbon so that our team can easily find your questions and provide
answers.
If you can't find an answer on the user forum, you can email the WSO2 development team directly using the relevant
mailing lists listed at http://wso2.org/mail.

Report issues

Report issues, submit enhancement requests, contribute samples and tips & tricks, and track and comment on

Copyright WSO2 Inc. 2005-2014 9


WSO2 Carbon 4.1.0

issues using our public bug-tracking system.

Export and print

To export this documentation or a selected portion of it, click the 'Browse' menu at the top of this screen, click
'Advanced', and then click one of the export options. To print the documentation, export to PDF and then use the
P D F p r i n t o p t i o n s .

About this Release


WSO2 Carbon version 4.1.0 is the successor of version 4.0.0. It contains the following new features and
enhancements:

What's New in this Release

JSP/Apache Tomcat library upgrade


New class loading hierarchy for web-apps that allows users to control the visibility of the Carbon platform
provided libs
Equinox SDK 3.8.1
Stabilizing WSO2 Carbon

What information is new

This following information on Carbon Kernel patching has been added newly to this release,
Creating a Carbon kernel patch
Shipping a kernel patch with distribution
Applying a patch to the kernel
Adding external libraries
For more information, see the Developer Guide

Bug fixes

For list of fixed issues, refer to WSO2 Carbon Server 4.1.0 - Fixed Issues.

Known issues

For a list of known issues, refer to WSO2 Carbon 4.1.0 - Known Issues .

Copyright WSO2 Inc. 2005-2014 10


WSO2 Carbon 4.1.0

Installation Guide
This chapter contains the following information:
Downloading the Product
Installation Prerequisites
Installing the Product
Running the Product
Introducing the Management Console
Downloading the Product
Follow the instructions below to download the product from the product web page. You can also download and build
the source code.

1. In your Web browser, go to http://wso2.com/products/carbon/.


2. If you are a new user downloading WSO2 products for the first time, register and log in.
3. Once you are logged in, click the Binary button in the upper right corner of the page.
The binary distribution contains the Carbon binary files for both MS Windows and Linux operating systems,
compressed into a single ZIP file. This distribution is recommended for many users.
Installation Prerequisites
Prior to installing any WSO2 Carbon based product, it is necessary to have the appropriate prerequisite software
installed on your system. Verify that the computer has the supported operating system and development platforms
before starting the installation.

System requirements

Memory 1 GB minimum
A heap size of around 512MB is generally sufficient to process typical SOAP messages
Requirements may vary with larger message sizes and on the number of messages processed
concurrently

Disk Approximately 500 MB, excluding space allocated for log files and Databases.

Environment compatibility

Operating As all WSO2 Carbon-based products are Java applications, it is generally possible to run them
Systems / on most operating systems. These include Windows, Linux, Solaris, Ubuntu, Fedora, Mac
Databases OS X, Gentoo, SUSE, Debian etc. with a JDK 1.6.x runtime.
However, Linux/Solaris are recommended for a production deployment.
All WSO2 Carbon-based products are generally compatible with most-common DBMSs such as
MySQL, MS SQL Server, Oracle, H2, DB2, Derby, PostgreSQL.

Required applications

Application Purpose Version Notes

Copyright WSO2 Inc. 2005-2014 11


WSO2 Carbon 4.1.0

Oracle Java To launch the product as 1.6.x or higher Required to


S E each product is a Java launch
Development application. If you are using JDK 1.6, you might need to WSO2
Kit (JDK) To build the product from the install Java Cryptography Extension (JCE) Carbon as it
Source distribution (both JDK Unlimited Strength Jurisdiction Policy files is a Java
and Apache Maven are to avoid "illegal key size" errors when you application.
required). try to invoke a secured web service.
To run Apache Ant. If you want to build the product from the
source distribution, you must use JDK 1.6
instead of JDK 1.7.
Oracle and IBM JRE 1.7 are also supported
when running (not building) WSO2
products.

Apache Ant To compile and run the 1.7.0 or later Required to


sample clients. run product
samples.

Apache To build the product from the 2.1.0 or later Required


Maven Source distribution (both JDK when
and Apache Maven are installing
required). from source
distribution.

Web To access the product's Screen resolution of 1024x768 is Required to


Browser Management Console. The recommended. run the
Web Browser must be management
JavaScript-enabled to take console.
full advantage of the
management console.
NOTE: On Windows Server
2003, it is not allowed to go
below the medium security
level in Internet Explorer 6.x.

Installing the Product


Installing WSO2 is very fast and easy. Before you begin, be sure you have met the installation prerequisites, and
then follow the installation instructions for your platform.
Installing on Linux
Installing on Solaris
Installing on Windows
Installing as a Windows Service
Installing as a Linux Service
Installing on Linux

Follow the instructions below to install the required applications and the WSO2 product on Linux.

Install the required applications

1. Establish an SSH connection to the Linux machine or log in on the text Linux console.
Installation Prerequisites
2. Be sure your system meets the , Java Development Kit (JDK) is essential to run the
product.

Installing the product

1. If you have not done so already, download the latest version of the product as described in Downloading the

Copyright WSO2 Inc. 2005-2014 12


WSO2 Carbon 4.1.0
1.

.Product
2. Extract the archive file to a dedicated directory for the product, which will hereafter be referred to as <PRODUC
T_HOME>.

Setting JAVA_HOME

You must set your JAVA_HOME environment variable to point to the directory where the Java Development Kit (JDK)
is installed on the computer.

Environment variables are global system variables accessible by all the processes running under the
operating system.

1. In your home directory, open the BASHRC file in your favorite Linux text editor, such as vi, emacs, pico, or
mcedit.
2. Add the following two lines at the bottom of the file, replacing /usr/java/jdk1.6.0_25 with the actual
directory where the JDK is installed.

export JAVA_HOME=/usr/java/jdk1.6.0_25
export PATH=${JAVA_HOME}/bin:${PATH}

The file should now look like this:

3. Save the file.

If you do not know how to work with text editors in a Linux SSH session, run the following command:

cat >> .bashrc

Paste the string from the clipboard and press "Ctrl+D."

4. To verify that the JAVA_HOME variable is set correctly, execute the following command:

echo $JAVA_HOME

The system returns the JDK installation path.

Setting system properties

Copyright WSO2 Inc. 2005-2014 13


WSO2 Carbon 4.1.0

If you need to set additional system properties when the server starts, you can take the following approaches:
Set the properties from a script. Setting your system properties in the startup script is ideal, because it
ensures that you set the properties every time you start the server. To avoid having to modify the script each
time you upgrade, the best approach is to create your own startup script that wraps the WSO2 startup script
and adds the properties you want to set, rather than editing the WSO2 startup script directly.
Set the properties from an external registry. If you want to access properties from an external registry, you
could create Java code that reads the properties at runtime from that registry. Be sure to store sensitive data
such as username and password to connect to the registry in a properties file instead of in the Java code and
secure the properties file with the secure vault.

SUSE Linux
When using SUSE Linux, it ignores /etc/resolv.conf and only looks at the /etc/hosts file. This
means that the server will throw an exception on startup if you have not specified anything besides
localhost. To avoid this error, add the following line above 127.0.0.1 localhost in the /etc/hosts file
: <ip_address> <machine_name> localhost.

You are now ready to run the product.


Installing on Solaris

Follow the instructions below to install the required applications and the product on Solaris.

Installing the supporting applications

1. Establish an SSH connection to the Solaris machine or log in on the text console.
Installation Prerequisites
2. Be sure your system meets the , Java Development Kit (JDK) is essential to run the
product.

Installing the product

1. If you have not done so already, download the latest version of the product as described in Downloading the
.Product
2. Extract the archive file to a dedicated directory for the product, which will hereafter be referred to as <PRODUC
T_HOME>.

Setting JAVA_HOME

You must set your JAVA_HOME environment variable to point to the directory where the Java Development Kit (JDK)
is installed on the computer.

Environment variables are global system variables accessible by all the processes running under the
operating system.

1. In your home directory, open the BASHRC file in your favorite text editor, such as vi, emacs, pico, or mcedit.
2. Add the following two lines at the bottom of the file, replacing /usr/java/jdk1.6.0_25 with the actual
directory where the JDK is installed.

export JAVA_HOME=/usr/java/jdk1.6.0_25
export PATH=${JAVA_HOME}/bin:${PATH}

Copyright WSO2 Inc. 2005-2014 14


WSO2 Carbon 4.1.0

The file should now look like this:

3. Save the file.

If you do not know how to work with text editors in an SSH session, run the following command:

cat >> .bashrc

Paste the string from the clipboard and press "Ctrl+D."

4. To verify that the JAVA_HOME variable is set correctly, execute the following command: echo $JAVA_HOME

The system returns the JDK installation path.

Setting system properties

If you need to set additional system properties when the server starts, you can take the following approaches:
Set the properties from a script. Setting your system properties in the startup script is ideal, because it
ensures that you set the properties every time you start the server. To avoid having to modify the script each
time you upgrade, the best approach is to create your own startup script that wraps the WSO2 startup script
and adds the properties you want to set, rather than editing the WSO2 startup script directly.
Set the properties from an external registry. If you want to access properties from an external registry, you
could create Java code that reads the properties at runtime from that registry. Be sure to store sensitive data
such as username and password to connect to the registry in a properties file instead of in the Java code and
secure the properties file with the secure vault.
You are now ready to run the product.
Installing on Windows

Follow the instructions below to install the required applications and the product on Windows.

Installing the supporting applications

Installation PrerequisitesBe sure your system meets the , Java Development Kit (JDK) is essential to run the
product.

Installing the product

1. If you have not done so already, download the latest version of the product as described in Downloading the
Product.
2. Extract the archive file to a dedicated directory for the product, which will hereafter be referred to as <PRODUC
T_HOME>.

Copyright WSO2 Inc. 2005-2014 15


WSO2 Carbon 4.1.0

Setting JAVA_HOME

You must set your JAVA_HOME environment variable to point to the directory where the Java Development Kit (JDK)
is installed on the computer. Typically, the JDK is installed in a directory under C:\Program Files\Java, such as
C:\Program Files\Java\jdk1.6.0_27 . If you have multiple versions installed, choose the latest one, which
you can find by sorting by date.

Environment variables are global system variables accessible by all the processes running under the
operating system. You can define an environment variable as a system variable, which applies to all users,
or as a user variable, which applies only to the user who is currently logged in.

You can set JAVA_HOME using the System Properties, as described below. Alternatively, if you just want to set
JAVA_HOME temporarily in the current command prompt window, set it at the command prompt.
Setting JAVA_HOME using the System Properties
1. Right-click the "My Computer" icon on the desktop and choose Properties.

2. In the System Properties window, click the Advanced tab, and then click the Environment Variables button.

Copyright WSO2 Inc. 2005-2014 16


WSO2 Carbon 4.1.0

3. Click the Newbutton under "System variables" (for all users) or under "User variables" (just for the user who is
currently logged in).

4. Enter the following information:


In the "Variable name" field, enter: JAVA_HOME
In the "Variable value" field, enter the installation path of the Java Development Kit, such as: c:\Prog
ram Files\Java jdk1.6.0_27
5. Click OK.
The JAVA_HOME variable is now set and will apply to any subsequent command prompt windows you open. If you
have existing command prompt windows running, you must close and reopen them for the JAVA_HOME variable to
take effect, or manually set the JAVA_HOME variable in those command prompt windows as described in the next
section. To verify that the JAVA_HOME variable is set correctly, open a command window (from the Start menu, click
Run, and then type CMD and click Enter) and execute the following command:

Copyright WSO2 Inc. 2005-2014 17


WSO2 Carbon 4.1.0

set JAVA_HOME

The system returns the JDK installation path.


Setting JAVA_HOME temporarily using the Windows command prompt (CMD)
You can temporarily set the JAVA_HOME environment variable within a Windows command prompt window (CMD).
This is useful when you have an existing command prompt window running and you do not want to restart it.
1. In the command prompt window, enter the following command where <JDK_INSTALLATION_PATH> is the
JDK installation directory and press Enter: set JAVA_HOME=<JDK_INSTALLATION_PATH>

For example:
set JAVA_HOME=c:\Program Files\java\jdk1.6.0_27

The JAVA_HOME variable is now set for the current CMD session only.
2. To verify that the JAVA_HOMEvariable is set correctly, execute the following command:
set JAVA_HOME

The system returns the JDK installation path.

Setting system properties

If you need to set additional system properties when the server starts, you can take the following approaches:
Set the properties from a script. Setting your system properties in the startup script is ideal, because it
ensures that you set the properties every time you start the server. To avoid having to modify the script each
time you upgrade, the best approach is to create your own startup script that wraps the WSO2 startup script
and adds the properties you want to set, rather than editing the WSO2 startup script directly.
Set the properties from an external registry. If you want to access properties from an external registry, you
could create Java code that reads the properties at runtime from that registry. Be sure to store sensitive data
such as username and password to connect to the registry in a properties file instead of in the Java code and
secure the properties file with the secure vault.
You are now ready to run the product.
Installing as a Windows Service

WSO2 Carbon and any Carbon-based product can be run as a Windows service as described in the following
sections:
Prerequisites
Setting up the YAJSW wrapper configuration file
Setting up PRODUCT_HOME
Running the product in console mode
Working with the WSO2CARBON service

Prerequisites

Install JDK 1.6 or higher and set up the JAVA_HOME environment variable.
Download and install a service wrapper library to use for running your WSO2 product as a Windows service.
WSO2 recommends Yet Another Java Service Wrapper (YAJSW) 11.03, and several WSO2 products provide
a default wrapper.conf file in their <PRODUCT_HOME>/bin/yajsw directory. The instructions below
describe how to set up this file.

Setting up the YAJSW wrapper configuration file

The configuration file used for wrapping Java Applications by YAJSW is wrapper.conf, which is located in the <Y
AJSW_HOME>/conf directory and in the <PRODUCT_HOME>bin/yajsw directory of many WSO2 products.

Copyright WSO2 Inc. 2005-2014 18


WSO2 Carbon 4.1.0

Following is the minimal wrapper.conf configuration for running a WSO2 product as a Windows service. Open
your wrapper.conf file, set its properties as follows, and save it in <YAJSW_HOME>/conf directory.

If you want to set additional properties from an external registry at runtime, store sensitive information like
usernames and passwords for connecting to the registry in a properties file and secure it with secure vault.

Minimal wrapper.conf configuration


#********************************************************************
# working directory
#********************************************************************
wrapper.working.dir=${carbon_home}\\
# Java Main class.
# YAJSW: default is "org.rzo.yajsw.app.WrapperJVMMain"
# DO NOT SET THIS PROPERTY UNLESS YOU HAVE YOUR OWN IMPLEMENTATION
# wrapper.java.mainclass=
#********************************************************************
# tmp folder
# yajsw creates temporary files named in_.. out_.. err_.. jna..
# per default these are placed in jna.tmpdir.
# jna.tmpdir is set in setenv batch file to <yajsw>/tmp
#********************************************************************
wrapper.tmp.path = ${jna_tmpdir}
#********************************************************************
# Application main class or native executable
# One of the following properties MUST be defined
#********************************************************************
# Java Application main class
wrapper.java.app.mainclass=org.wso2.carbon.bootstrap.Bootstrap
# Log Level for console output. (See docs for log levels)
wrapper.console.loglevel=INFO
# Log file to use for wrapper output logging.
wrapper.logfile=${wrapper_home}\/log\/wrapper.log
# Format of output for the log file. (See docs for formats)
#wrapper.logfile.format=LPTM
# Log Level for log file output. (See docs for log levels)
#wrapper.logfile.loglevel=INFO
# Maximum size that the log file will be allowed to grow to before
# the log is rolled. Size is specified in bytes. The default value
# of 0, disables log rolling by size. May abbreviate with the 'k' (kB) or
# 'm' (mB) suffix. For example: 10m = 10 megabytes.
# If wrapper.logfile does not contain the string ROLLNUM it will be automatically
added as suffix of the file name
wrapper.logfile.maxsize=10m
# Maximum number of rolled log files which will be allowed before old
# files are deleted. The default value of 0 implies no limit.
wrapper.logfile.maxfiles=10
# Title to use when running as a console
wrapper.console.title="WSO2 Carbon"
#********************************************************************
# Wrapper Windows Service and Posix Daemon Properties
#********************************************************************
# Name of the service
wrapper.ntservice.name="WSO2CARBON"
# Display name of the service
wrapper.ntservice.displayname="WSO2 Carbon"
# Description of the service

Copyright WSO2 Inc. 2005-2014 19


WSO2 Carbon 4.1.0

wrapper.ntservice.description="Carbon Kernel"
#********************************************************************
# Wrapper System Tray Properties
#********************************************************************
# enable system tray
wrapper.tray = true
# TCP/IP port. If none is defined multicast discovery is used to find the port
# Set the port in case multicast is not possible.
wrapper.tray.port = 15002
#********************************************************************
# Exit Code Properties
# Restart on non zero exit code
#********************************************************************
wrapper.on_exit.0=SHUTDOWN
wrapper.on_exit.default=RESTART
#********************************************************************
# Trigger actions on console output
#********************************************************************
# On Exception show message in system tray
wrapper.filter.trigger.0=Exception
wrapper.filter.script.0=scripts\/trayMessage.gv
wrapper.filter.script.0.args=Exception
#********************************************************************
# genConfig: further Properties generated by genConfig
#********************************************************************
placeHolderSoGenPropsComeHere=
wrapper.java.command = ${java_home}\\bin\\java
wrapper.java.classpath.1 = ${java_home}\\lib\\tools.jar
wrapper.java.classpath.2 = ${carbon_home}\\bin\\*.jar
wrapper.app.parameter.1 = org.wso2.carbon.bootstrap.Bootstrap
wrapper.app.parameter.2 = RUN
wrapper.java.additional.1 = -Xbootclasspath\/a:${carbon_home}\\lib\\xboot\\*.jar
wrapper.java.additional.2 = -Xms256m
wrapper.java.additional.3 = -Xmx1024m
wrapper.java.additional.4 = -XX:MaxPermSize=256m
wrapper.java.additional.5 = -XX:+HeapDumpOnOutOfMemoryError
wrapper.java.additional.6 =
-XX:HeapDumpPath=${carbon_home}\\repository\\logs\\heap-dump.hprof
wrapper.java.additional.7 = -Dcom.sun.management.jmxremote
wrapper.java.additional.8 =
-Djava.endorsed.dirs=${carbon_home}\\lib\\endorsed;${java_home}\\jre\\lib\\endorsed
wrapper.java.additional.9 = -Dcarbon.registry.root=\/
wrapper.java.additional.10 = -Dcarbon.home=${carbon_home}
wrapper.java.additional.11 = -Dwso2.server.standalone=true
wrapper.java.additional.12 = -Djava.command=${java_home}\\bin\\java
wrapper.java.additional.13 = -Djava.io.tmpdir=${carbon_home}\\tmp
wrapper.java.additional.14 = -Dcatalina.base=${carbon_home}\\lib\\tomcat
wrapper.java.additional.15 =
-Djava.util.logging.config.file=${carbon_home}\\repository\\conf\\log4j.properties
wrapper.java.additional.16 = -Dcarbon.config.dir.path=${carbon_home}\\repository\\conf

wrapper.java.additional.17 = -Dcarbon.logs.path=${carbon_home}\\repository\\logs
wrapper.java.additional.18 =
-Dcomponents.repo=${carbon_home}\\repository\\components\\plugins
wrapper.java.additional.19 = -Dconf.location=${carbon_home}\\repository\\conf
wrapper.java.additional.20 =
-Dcom.atomikos.icatch.file=${carbon_home}\\lib\\transactions.properties
wrapper.java.additional.21 = -Dcom.atomikos.icatch.hide_init_file_path=true
wrapper.java.additional.22 =

Copyright WSO2 Inc. 2005-2014 20


WSO2 Carbon 4.1.0

-Dorg.apache.jasper.runtime.BodyContentImpl.LIMIT_BUFFER=true

Copyright WSO2 Inc. 2005-2014 21


WSO2 Carbon 4.1.0

wrapper.java.additional.23 = -Dcom.sun.jndi.ldap.connect.pool.authentication=simple
wrapper.java.additional.24 = -Dcom.sun.jndi.ldap.connect.pool.timeout=3000
wrapper.java.additional.25 = -Dorg.terracotta.quartz.skipUpdateCheck=true

Setting up PRODUCT_HOME

Extract the Carbon based product that you want to run as a Windows service, and then set the Windows
environment variable CARBON_HOME to the extracted product directory location. For example, if you want to run
Carbon 4.1.0 as a Windows service, you would set PRODUCT_HOME to the extracted wso2carbon-4.1.0 directory.

Running the product in console mode

You will now verify that YAJSW is configured correctly for running the Carbon based product as a Windows service.
1. Open a Windows command prompt and go to the <YAJSW_HOME>/bat directory. For example:

cd C:\Documents and Settings\yajsw_home\bat

2. Start the wrapper in console mode using the following command:

runConsole.bat

For example:

If the configurations are set properly for YAJSW, you will see the console output similar to the following and can now
access the WSO2 management console from your web browser via https://localhost:9443/carbon.

Working with the WSO2CARBON service

To install the Carbon based product as a Windows service, execute the following command in the <YAJSW_H
OME>/bat directory:

installService.bat

The console will display a message confirming that the WSO2CARBON service was installed.

Copyright WSO2 Inc. 2005-2014 22


WSO2 Carbon 4.1.0

To start the service, execute the following command in the same console window:

startService.bat

The console will display a message confirming that the WSO2CARBON service was started.

To stop the service, execute the following command in the same console window:

stopService.bat

The console will display a message confirming that the WSO2CARBON service has stopped.

Copyright WSO2 Inc. 2005-2014 23


WSO2 Carbon 4.1.0

To uninstall the service, execute the following command in the same console window:

uninstallService.bat

The console will display a message confirming that the WSO2CARBON service was removed.

Installing as a Linux Service

Follow the sections below to run a WSO2 product as a Linux service:


Prerequisites
Setting up CARBON_HOME
Running the product as a Linux service

Prerequisites

Install JDK 1.6.24 or later or 1.7.* and set up the JAVA_HOME environment variable.

Setting up CARBON_HOME

Extract the WSO2 product to a preferred directory in your machine and set the environment variable CARBON_HOME
to the extracted directory location.

Running the product as a Linux service

Copyright WSO2 Inc. 2005-2014 24


WSO2 Carbon 4.1.0

1. To run the product as a service, create a startup script and add it to the boot sequence. The basic structure of
the startup script has three parts (i.e., start, stop and restart) as follows:

#!/bin/bash

case $1 in
start)
echo Starting the Service
;;
stop)
echo Stopping the Service
;;
restart)
echo Restarting the Service
;;
*)
echo $Usage: $0 {start|stop|restart}
exit 1
esac

Given below is a sample startup script. <PRODUCT_HOME> can vary depending on the WSO2 product's
directory.

#! /bin/sh
export JAVA_HOME="/usr/lib/jvm/jdk1.7.0_07"

startcmd='<PRODUCT_HOME>/bin/wso2server.sh start > /dev/null &'


restartcmd='<PRODUCT_HOME>/bin/wso2server.sh restart > /dev/null &'
stopcmd='<PRODUCT_HOME>/bin/wso2server.sh stop > /dev/null &'

case "$1" in
start)
echo "Starting the WSO2 Server ..."
su -c "${startcmd}" user1
;;
restart)
echo "Re-starting the WSO2 Server ..."
su -c "${restartcmd}" user1
;;
stop)
echo "Stopping the WSO2 Server ..."
su -c "${stopcmd}" user1
;;
*)
echo "Usage: $0 {start|stop|restart}"
exit 1
esac

In the above script, the server is started as a user by the name user1 rather than the root user. For example,
su -c "${startcmd}" user1
2. Add the script to /etc/init.d/ directory.

If you want to keep the scripts in a location other than /etc/init.d/ folder, you can add a symbolic
link to the script in /etc/init.d/ and keep the actual script in a separate location. Say your script

Copyright WSO2 Inc. 2005-2014 25


WSO2 Carbon 4.1.0

name is prodserver and it is in /opt/WSO2/ folder, then the commands for adding a link to /etc/in
it.d/ is as follows:

Make executable: sudo chmod a+x /opt/WSO2/prodserver


Add a link to /etc/init.d/: sudo ln -snf /opt/WSO2/prodserver
/etc/init.d/prodserver

3. Install the startup script to respective runlevels using the command update-rc.d. For example, give the
following command for the sample script shown in step1:

sudo update-rc.d prodserver defaults

The defaults option in the above command makes the service to start in runlevels 2,3,4 and 5 and to stop
in runlevels 0,1 and 6.
A runlevel is a mode of operation in Linux (or any Unix-style operating system). There are several runlevels
in a Linux server and each of these runlevels is represented by a single digit integer. Each runlevel
designates a different system configuration and allows access to a different combination of processes.
4. You can now start, stop and restart the server using service <service name> {start|stop|restart
} command. You will be prompted for the password of the user (or root) who was used to start the service.

Running the Product


To run WSO2 products, you start the product server at the command line. You can then run the Management
Console application to configure and manage the product. This page describes how to run the product in the
following sections:
Starting the Server
Running the Management Console
Stopping the Server

The Management Console uses the default HTTP-NIO transport, which is configured in the catalina-ser
ver.xml file in the <PRODUCT_HOME>/repository/conf/tomcat directory. This transport must be
properly configured in this file for the Management Console to be accessible.

Starting the Server

To start the server, you run the script wso2server.bat (on Windows) or wso2server.sh (on Linux/Solaris) from
the bin folder. Alternatively, you can install and run the server as a Windows service.

To start and stop the server in the background mode of Linux, run wso2server.sh start and wso2serv
er.sh stop commands.

1. Open a command prompt:


On Windows, choose Start -> Run, type cmd at the prompt, and press Enter.
On Linux/Solaris, establish a SSH connection to the server or log in to the text Linux console.
2. Execute one of the following commands, where <PRODUCT_HOME> is the directory where you installed the
product distribution:

OS Command

Copyright WSO2 Inc. 2005-2014 26


WSO2 Carbon 4.1.0

On Windows <PRODUCT_HOME>\bin\wso2server.bat

On Linux/Solaris sh
<PRODUCT_HOME>/bin/wso2server.sh

If you want to provide access to the production environment without allowing any user group
(including admin) to log into the management console, execute one of the following commands.
On Windows: <PRODUCT_HOME>\bin\wso2server.bat --run -DworkerNode
On Linux/Solaris: sh <PRODUCT_HOME>/bin/wso2server.sh -DworkerNode

If you want to check any additional options available to be used with the startup commands, type -he
lp after the command, such as: sh <PRODUCT_HOME>/bin/wso2server.sh -help.

The operation log appears. When the product server is running, the log displays the message "WSO2 Carbon
started in 'n' seconds".

Running the Management Console

Once the server has started, you can run the Management Console by opening a Web browser and typing in the
management console's URL. The URL is displayed as the last line in the start script's console and log. For example:

The URL should be in the following format: https://<Server Host>:9443/carbon

You can use this URL to access the Management Console on this computer from any other computer connected to
the Internet or LAN. When accessing the Management Console from the same server where it's installed, you can
type "localhost" instead of the IP address: https://localhost:9443/carbon

Copyright WSO2 Inc. 2005-2014 27


WSO2 Carbon 4.1.0

At the sign-in screen, sign in to the Management Console using admin as both the username and password.
You can then use the Management Console to manage the product. The tabs and menu items in the
navigation pane on the left may vary depending on the features you have installed.

To view information about a particular page, click the Help link in the top right corner of that page , or click the
Docs link to open this documentation for full information on managing the product.

When the Management Console Sign-in page appears, the web browser will typically display an
"insecure connection" message, which requires your confirmation before you can continue.
The Management Console is based on the HTTPS protocol, which is a combination of HTTP and
SSL protocols. This protocol is generally used to encrypt the traffic from the client to server for
security reasons. The certificate it works with is used for encryption only, and does not prove the
server identity, so when you try to access the Management Console, a warning of untrusted
connection is usually displayed. To continue working with this certificate, some steps should be taken
to "accept" the certificate before access to the site is permitted. If you are using the Mozilla Firefox
browser, this usually occurs only on the first access to the server, after which the certificate is stored
in the browser database and marked as trusted. However, with other browsers, the insecure
connection warning might be displayed every time you access the server.
This scenario is suitable for testing purposes, or for running the program on the company's internal
networks. If you want to make the Management Console available to external users, your
organization should obtain a certificate signed by a well-known certificate authority, which verifies that
the server actually has the name it is accessed by and that this server belongs to the given
organization.

If you leave the Management Console unattended, the session will time out. The default timeout value is 15
minutes, but you can change this in the <PRODUCT_HOME>/repository/conf/tomcat/carbon/WEB-IN
F/web.xml file as follows:

<session-config>
<session-timeout>15</session-timeout>
</session-config>

Stopping the Server

To stop the server, press Ctrl+C in the command window, or click the Shutdown/Restart link in the navigation pane
in the Management Console.

Introducing the Management Console


The WSO2 Carbon Management console is a Web-based user interface powered by JSP and AJAX. It allows users
to interact with a running Carbon instance, without having to directly interfere with any underlying configuration files.
The Management Console makes use of the default HTTPS servlet transport, which is configured in the
catalina-server.xml file in directory <PRODUCT_HOME>/repository/conf/tomcat. It is essential for this transport to be
properly configured in this file for the Management Console to be accessible by users.

Accessing the management console

Copyright WSO2 Inc. 2005-2014 28


WSO2 Carbon 4.1.0

Make sure you have run the product by executing the shell script (for Linux/Solaris) or the batch file (for Windows)
as explained in the previous section. With any WSO2 product properly installed, you can access its Management
Console (Web interface) by opening a Web browser and typing in the management console's URL as it appears in
the start script's log. For example,

Accessing from internet/LAN


To connect to the product's Web Interface from any computer connected to Internet/LAN, follow the instructions
below.
1. Open a Web browser and access the real IP of the server. Typically, it is the IP address of the computer. The
URL should be in the following format:

https://<Server Host>:9443/carbon.

2. The product's homepage opens.


Accessing from local machine
1. You can also connect to the product's Web Interface from the computer where it is installed by typing "localhost" i
nstead of the IP.

https://localhost:9443/carbon

2. Once you have established a connection, the Management Console opens in the anonymous mode.

When the product's homepage opens, it is possible that the Internet browser will display an "insecure
connection" message, requiring your confirmation of being aware of the risks.
The Management Console is based on HTTPS protocol, which is a combination of HTTP and SSL
protocols. This protocol is generally used to encrypt the traffic from the client to server for security
reasons. The certificate it works with is used for encryption only, and does not prove the server
identity. So when the users try to access the Management Console, a warning of untrusted
connection is usually displayed. In order to continue working with this certificate, some steps should
be taken to "accept" the certificate before access to the site is permitted. In case Mozilla Firefox
browser is used, this usually occurs only on the first access to the server. Then the certificate is
stored in the browser database marked as trusted. In case of some other browsers are used,
insecure connection warning may be displayed every time server is accessed.
This scenario is suitable for testing purposes, or for running the program on the company's internal
networks. But in case there is a need to provide an interface to the outside world, a company should
obtain a certificate signed by a well-known CA. The role of a CA is to verify that the server accessed
actually has the name it is accessed by, and that this server actually belongs to the given
organization.

The homepage of the Management Console opens. It typically has the following sections:

Copyright WSO2 Inc. 2005-2014 29


WSO2 Carbon 4.1.0

Menu items

Anonymous users can access some menu items including the "Home" menu displayed on the left-hand-side panel.

Links to resources

The panel at the center provides links to several resources as follows:


The product's online documentation.
The product's forum.
Link to the product's issue tracking system.
The mailing lists at http://wso2.org/mail.

Sign-in section

To access more controls, you need to log-in to the Management Console using the log-in panel at the
right-hand-side. Type in admin as the default Username and admin as the default Password. Click on "Sign-in".
For example,

You will be logged in to the product's Management Console.

Copyright WSO2 Inc. 2005-2014 30


WSO2 Carbon 4.1.0

The controls in the Management Console are usually self-explanatory. However, the context-sensitive help tips,
accessible by clicking the 'Help' link at the top right corner of any page, are a fast and easy way to get more
information, if required. The product documentation provides further information about the technology and
configurations.
The console's menu items appear in the left hand side. Usually they are divided as Main, Monitor, Configure and T
ools although additional menus may appear depending on the availability of features. Each of these menus carries
a list of sub menus. A product's menus and sub menus may vary depending on the product version and any
additional feature you have installed to provision the server.

If you leave the Management Console unattended for a defined time, its login session will time out. The default
timeout value is 15 minutes, but you can change this in <PRODUCT_HOME>/repository/conf/tomcat/carbon/WE
B-INF/web.xml file as follows:

<session-config>
<session-timeout>15</session-timeout>
</session-config>

Copyright WSO2 Inc. 2005-2014 31


WSO2 Carbon 4.1.0

User Guide
The user guide provides information about features, functionality, solution development, configuration, testing and
debugging options of WSO2 Carbon. The following topics take you through the entire breath of the product:
User Management
Feature Management
Server Roles for cApps
Transport Management
User Management
This chapter contains the following information:
Introduction to User Management
Users and Roles Configuration
Configuring User Stores

Screenshots in this section are taken using the WSO2 Carbon product. They may vary depending on the
product and the configuration options you are using.

Introduction to User Management

User management is a mechanism which involves defining and managing users, roles and their access levels in a
system. A user management dashboard or console provides system administrators a holistic view of a system's
active user sessions, their log-in statuses, the privileges of each user and their activity in the system, enabling the
system admins to make business-critical, real-time security decisions. A typical user management implementation
involves a wide range of functionality such as adding/deleting users, controlling user activity through permissions,
managing user roles, defining authentication policies, managing external user stores, manual/automatic log-out,
resetting user passwords etc.
Any user management system has users, roles, user stores and user permissions as its basic components.

Users

Users are consumers who interact with your organizational applications, databases or any other systems. These
users can be a person, a device or another application/program within or outside of the organization's network.
Since these users interact with internal systems and access data, the need to define which user is allowed to do
what is critical to most security-conscious organizations. This is how the concept of user management developed.

User stores

A user store is the database where information of the users and/or user roles is stored. User information includes
log-in name, password, fist name, last name, e-mail etc.
The user stores of all WSO2 Carbon-based products are embedded H2 databases except for WSO2 Identity Server,
which has an embedded LDAP as its user store. In Carbon, permission is stored in a separate database called the
user management database, which by default is H2. However, users have the ability to connect to external user
stores as well.
The user stores of Carbon products can be configured to operate in either one of the following modes.
User store operates in read/write mode - In Read/Write mode, WSO2 Carbon reads/writes into the user store.
User store operates in read only mode - In Read Only mode, WSO2 Carbon guarantees that it does not
modify any data in the user store. Carbon maintains roles and permissions in the Carbon database but it can
read users/roles from the configured user store.

Permission

A permission is a 'delegation of authority' or a 'right' assigned to a user or a group of users to perform an action on a
system. Permissions can be granted to or revoked from a user/user group/user role automatically or by a system

Copyright WSO2 Inc. 2005-2014 32


WSO2 Carbon 4.1.0

administrator. For example, if a user has the permission to log-in to a systems, then the permission to log-out is
automatically implied without the need of granting it specifically.

User roles

A user role is a consolidation of several permissions. Instead of associating permissions with a user, admins can
associate permissions with a user role and assign the role to users. User roles can be reused throughout the system
and prevents the overhead of granting multiple permissions to each and every user individually.

User management in WSO2 Carbon

User management comes bundled with the WSO2 Carbon platform and facilitates the management and control of
user accounts and roles at different levels. Since it is integrated into the core Carbon platform, user management
capability is available by default in all WSO2 Carbon-based products.
The user store of Carbon products can be configured to operate in either one of the following modes.
User store operates in read/write mode - In Read/Write mode, WSO2 Carbon reads/writes into the user store.
User store operates in read only mode - In Read Only mode, WSO2 Carbon guarantees that it does not
modify any data in the user store. Carbon maintains roles and permissions in the Carbon database but it can
read users/roles from the configured user store.
The user kernal of WSO2 Carbon has the following features:
The concept of single user store which is either external or internal.
Ability to operate in read-only/read-write mode on your company's LDAP user stores.
Ability to work with Active Directory Directory Services (AD DS) and Active Directory Lightweight Directory
Services (AD LDS) in read write mode.
Supports any custom realm.
Roles can contain users from external user stores.
Improved configuration capability for external user stores.
Capability to read roles from LDAP/Active Directory user stores.
Implements management permission of the carbon console.
The user core is driven by the user-mgt.xml file found in: CARBON_HOME/repository/conf folder.

Users and Roles Configuration

This section provides information on adding/deleting users, user roles and changing passwords through a given
product's Management Console.
Adding and Deleting Users
Changing the Current User's Password
Resetting a User's Password
Adding and Deleting User Roles
Adding and Deleting Users
This documentation explains how you can create user accounts and roles to define access to the management
console of your product. Before you start, note the following:
The option of adding, modifying and removing user accounts and roles is only available for administrators
with privileges. Read about realm configurations for details on how to set up administrators.
The user stores of your product should already be set up and configured, so that the new users and roles you
create using the management console can be saved in them. Read about configuring user stores for more
d e t a i l s .
For example, the user name and password that you define for a new user will be validated against the
'RegEx' configurations of the user store at the time the user/role is created. This validation ensures that

Copyright WSO2 Inc. 2005-2014 33


WSO2 Carbon 4.1.0

details such as the length of password, user name, role name etc. conform to the requirements of the user
store. Shown below is the default 'RegEx' configuration for the primary user store in your product.

PasswordJavaRegEx-------- ^[\S]{5,30}$
PasswordJavaScriptRegEx-- ^[\S]{5,30}$
UsernameJavaRegEx-------- ^~!#$;%*+={}\\{3,30}$
UsernameJavaScriptRegEx-- ^[\S]{3,30}$
RolenameJavaRegEx-------- ^~!#$;%*+={}\\{3,30}$
RolenameJavaScriptRegEx-- ^[\S]{3,30}$

Go to the relevant topic listed below for details:


Adding a new user and assigning roles
Deleting an existing user

Adding a new user and assigning roles

Follow the instructions below to add a new user account and configure its role.
1. Log on to the product's Management Console. In the "Configure" menu, click "Users and Roles" to access "Syste
m User Store."
For example,

2. Then click on the "Users" link.

The "Users" link is only visible to users with "Admin" permission. It is used to add new user accounts and
modify or delete existing accounts.

3. Click on the "Add New User" link.

Copyright WSO2 Inc. 2005-2014 34


WSO2 Carbon 4.1.0

4. The "Add User" window opens. The first step requires you to enter the user name and password. If you want to
add a user with the default "Everyone" role, click "Finish". Else, click "Next" to define a user role other than the
default.

5. If you proceed to the next step, a window will appear for you to select the roles to be assigned to the user. This
can be done by selecting the appropriate check-boxes or using the "Select all"/"Unselect all" links.

6. Click "Finish" once done.


A new user account will be created with the specified roles. The user name is displayed in the "Users" list.

Copyright WSO2 Inc. 2005-2014 35


WSO2 Carbon 4.1.0

Deleting an existing user

Follow the instructions below to delete a user.


1. Log on to the product's Management Console and select "Users and Roles" under the "Configure" menu. For
example,

2. Then click on the "Users" link to view the users list.

3. From the list of users, select the one you want to delete and click the "Delete" link associated with it.

4. A confirmation request message is displayed. Click "Yes".

You can't undo this operation once performed.

Copyright WSO2 Inc. 2005-2014 36


WSO2 Carbon 4.1.0

Changing the Current User's Password

Follow the instructions below to change the password of the user currently logged in.
For example,

2. Click on the "Change My Password" link.

3. The "Change Password" window appears. Populate the required fields and click "Change".

If a user has forgotten the current password, they need to contact the administrator who can reset it without
the current password.

Copyright WSO2 Inc. 2005-2014 37


WSO2 Carbon 4.1.0

4. A notification is displayed that the current user's password has been changed. Click "OK".

Resetting a User's Password

A server administrator has the ability to reset a user's password.

You cannot change the user name of an existing user.

Follow the instructions below to reset a user's password.


1. Log on to the product's Management Console and select "Users and Roles" under the "Configure" menu.
For example,

2. Click on "Users" to open the users list.

3. Locate the required user and click the "Change Password" link associated with it.

4. The "Change Password" window opens. Fill in the required fields and click the "Change" button.

Copyright WSO2 Inc. 2005-2014 38


WSO2 Carbon 4.1.0

5. If the password change is successful, a message appears. Click "OK".

Adding and Deleting User Roles

Roles contain permissions for users to manage the Server. You can create different roles with various combinations
of permissions and assign them to a user or a group of users. Through the management console, you can also edit
and delete an existing user role.
Adding a User Role
Editing a User Role
Deleting a User Role

Adding a user role

Follow the instructions below to add a user role.


1. Log on to the product's Management Console and select "Users and Roles" under the "Configure" menu.
For example,

2. In the "User Management" window which appears, click the "Roles" link.

Copyright WSO2 Inc. 2005-2014 39


WSO2 Carbon 4.1.0

3. In the "Roles" window, click on the "Add New Role" link.

4. Enter the name for the role and click "Next". You can also click "Finish", in which case, the new roles will be
created with default permissions (none) and no assigned users.

5. If you proceed, you will be asked to select permission for the new role. Click "Next" once done.

6. Select the users that will be assigned to the role. You can conduct a search by name, or view all users by entering
"*" into the search field.

Copyright WSO2 Inc. 2005-2014 40


WSO2 Carbon 4.1.0

Click the "Finish" button once user is selected.


7. The new role is added to the list.

When Adding Roles to External User Stores


Some external user stores do not allow you to create empty roles. In that case, selecting users who belong to
a role is mandatory.
If you connect to an external user store in read only mode, you can read existing roles from it but you can not
edit/delete the roles. In this case, you can still create new roles which are editable and can be managed
internally.
If you connect to an external user store in read/write mode, you can edit the roles in the external user store as
well.

Editing a user role

1. Log on to the product's Management Console and select "Users and Roles" under the "Configure" menu.
2. In the "User Management" window which appears, click on the "Users" link.

3. From the list of users, find the user whose role you want to change and click the "Roles" link associated with it.

4. The window that opens contains information about the roles assigned to that user. Select the role you want to
assign using the check boxes and click "Update".

Copyright WSO2 Inc. 2005-2014 41


WSO2 Carbon 4.1.0

5. The user role will be changed. The program goes back to the user menu.

Deleting a user role

Follow the instructions below to delete a user role.


1. Log on to the product's Management Console and select "Users and Roles" under the "Configure" menu.
2. In the "User Management" window which appears, click the "Roles" link.

3. Click the "Delete" link associated with the role you want to delete.

4. Accept the confirmation request.

Copyright WSO2 Inc. 2005-2014 42


WSO2 Carbon 4.1.0

Configuring User Stores

See the topics given below for details on how user stores should be configured for your Carbon product:
Realm Configuration
Changing the RDBMS
Default JDBC User Store Configuration
Default LDAP User Store Configuration
Configuring External User Stores

Realm Configuration

The user-mgt.xml file's main configuration section has the following information:

<Configuration>
<AdminRole>admin</AdminRole>
<AdminUser>
<UserName>admin</UserName>
<Password>admin</Password>
</AdminUser>
<EveryOneRoleName>everyone</EveryOneRoleName> <!-- By default users in this role
sees the registry root -->
<Property name="dataSource">jdbc/WSO2CarbonDB</Property>
<Property
name="MultiTenantRealmConfigBuilder">org.wso2.carbon.user.core.config.multitenancy.Sim
pleRealmConfigBuilder</Property>
</Configuration>

The main elements of the Realm Configuration can be explained as follows.

Element Name Description

<AdminRole> Admin's role name.


This role has permission to carry out any action related to the Management
Console. If the user store is read-only, then this role is added to the system as a
special internal role where users are from an external user store.

<AdminUser>\<UserName> Admin user's username.


If the user store is read-only, the admin user must exist in the user store . Otherwise
the system won't start.

<AdminUser>\<Password> Admin user's password.


If the user store is read-only, this element and its value are ignored.

<EveryOneRoleName> Everyone role name.


All users in the system belong to this role.

The main properties of the user Realm Configuration can be explained as follows. It mainly contains details for the

Copyright WSO2 Inc. 2005-2014 43


WSO2 Carbon 4.1.0

database connection.

Property Name Description

dataSource Data sources are configured in the


<PRODUCT_HOME>/repository/conf/datasources/master-datasources.xml
file. This property indicates the relevant data source configuration for
the User Management Database.

MultiTenantRealmConfigBuilder Tenant Manager specific realm config parameter. Can be used to build
different types of realms for the tenant.

Changing the RDBMS

The default database of user manager is the H2 database shipped by the WSO2 Carbon based products. You can
configure it to point to databases by different vendors.
1. Add the JDBC driver to the classpath by dropping the JAR into <CARBON_HOME>/repository/components
/lib.

2. Change values of properties given in on the Realm Configuration page appropriately.


3. Create the database by running the relevant script in <CARBON_HOME>/dbscript/ and start the server as:

For Linux:

sh wso2server.sh

For Windows:

wso2server.bat

Or start the server as:


For Linux:

sh wso2server.sh -Dsetup

For Windows:

wso2server.bat -Dsetup

Default JDBC User Store Configuration

The default JDBC user store reads/writes into the internal database of the Carbon server. Internal JDBC user stores
can be configured using <PRODUCT_HOME>/repository/conf/user-mgt.xml file's JDBCUserStoreManager
configuration section.
The default configuration is shown below. Change the values according to your requirements. Note that the order in
which the properties are listed does not impact their usage in the system.

Copyright WSO2 Inc. 2005-2014 44


WSO2 Carbon 4.1.0

<UserStoreManager class="org.wso2.carbon.user.core.jdbc.JDBCUserStoreManager">
<Property name="ReadOnly">false</Property>
<Property name="MaxUserNameListLength">100</Property>
<Property name="IsEmailUserName">false</Property>
<Property name="DomainCalculation">default</Property>
<Property name="PasswordDigest">SHA-256</Property>
<Property name="StoreSaltedPassword">true</Property>
<Property name="UserNameUniqueAcrossTenants">false</Property>
<Property name="PasswordJavaRegEx">[\S]{5,30}$</Property>
<Property name="PasswordJavaScriptRegEx">[\\S]{5,30}</Property>
<Property
name="UsernameJavaRegEx">^[^~!#$;%^*+={}\\|\\\\&lt;&gt;,\'\"]{3,30}$</Property>
<Property name="UsernameJavaScriptRegEx">[\\S]{3,30}</Property>
<Property
name="RolenameJavaRegEx">^[^~!@#$;%^*+={}\\|\\\\&lt;&gt;,\'\"]{3,30}$</Property>
<Property name="RolenameJavaScriptRegEx">[\\S]{3,30}</Property>
<Property name="UserRolesCacheEnabled">true</Property>
</UserStoreManager>

The main elements of the above configuration are described below.

Property Name Description

ReadOnly Indicates whether the user store of this realm operates in the user read only
mode or not.

MaxUserNameListLength Maximum number of users retrieved at once by user real.

IsEmailUserName Indicates whether the email is used as username (apply when realm operates
in read only mode).

DomainCalculation Can be either default or custom (apply when realm operates in read only
mode).

PasswordDigest Digesting algorithm of the password. Has values such as PLAIN_TEXT, SHA
etc.

StoreSaltedPassword Indicates whether to salt the password.

UserNameUniqueAcrossTenants An attribute used for multi-tenancy.

PasswordJavaRegEx A regular expression to validate passwords. By default, strings having length 5


to 30 non-empty characters are allowed.

PasswordJavaScriptRegEx The regular expression used by the font-end components for password
validation.

UsernameJavaRegEx A regular expression to validate usernames. By default, strings having length


5 to 30 non-empty characters are allowed.

UsernameJavaScriptRegEx The regular expression used by the font-end components for username
validation.

RolenameJavaRegEx A regular expression to validate role names. By default, strings having length
5 to 30 non-empty characters are allowed.

Copyright WSO2 Inc. 2005-2014 45


WSO2 Carbon 4.1.0

RolenameJavaScriptRegEx The regular expression used by the font-end components for role name
validation.

UserRolesCacheEnabled This is to indicate whether to cache the role list of a user. By default it is 'true'.
Set it to 'false' if user-roles are changed by external means and those changes
should be instantly reflected in the Carbon instance.

In addition to the above properties, set the following also in the <PRODUCT_HOME>/repository/conf/user-mgt
.xml file.

1. MultiTenantRealmConfigBuilder property should be set to org.wso2.carbon.user.core.config


.multitenancy.SimpleRealmConfigBuilder. For example,

<Property
name="MultiTenantRealmConfigBuilder">org.wso2.carbon.user.core.config.multitenanc
y.SimpleRealmConfigBuilder</Property>

This property is described in section Realm Configuration


2. Add a property by the name passwordHashMethod to JDBCUserStoreManager default configuration
shown above and set the value to 'SHA' or 'PLAIN_TEXT'. For example,

<UserStoreManager class="org.wso2.carbon.user.core.jdbc.JDBCUserStoreManager">
...
<Property name="passwordHashMethod">SHA</Property>
...
</UserStoreManager>

3. Go to $PRODUCT_HOME/repository/conf/tenant-mgt.xml file and comment out the CommonHybridL


DAPTenantManager that is used by default and remove the comment for JDBCTenantManager. For
example,

<TenantManager
class="org.wso2.carbon.user.core.tenant.JDBCTenantManager"></TenantManager>

Default LDAP User Store Configuration

Following is the default configuration for the internal LDAP user store which is embedded ApacheDS LDAP. If
ApacheDSUserStoreManager is enabled in user-mgt.xml with following configuration, user manager reads/writes
into the default LDAP user store of Carbon.

Copyright WSO2 Inc. 2005-2014 46


WSO2 Carbon 4.1.0

<UserStoreManager
class="org.wso2.carbon.user.core.ldap.ReadWriteLDAPUserStoreManager">
<Property
name="ConnectionURL">ldap://localhost:${Ports.EmbeddedLDAP.LDAPServerPort}</Property>
<Property name="ConnectionName">uid=admin,ou=system</Property>
<Property name="ConnectionPassword">admin</Property>
<Property name="passwordHashMethod">SHA</Property>
<Property name="UserNameListFilter">(objectClass=person)</Property>
<Property name="UserEntryObjectClass">wso2Person</Property>
<Property name="UserSearchBase">ou=Users,dc=wso2,dc=org</Property>
<Property
name="UserNameSearchFilter">(&amp;(objectClass=person)(uid=?))</Property>
<Property name="UserNameAttribute">uid</Property>
<Property name="PasswordJavaScriptRegEx">[\\S]{5,30}</Property>
<Property name="UsernameJavaScriptRegEx">[\\S]{3,30}</Property>
<Property
name="UsernameJavaRegEx">^[^~!@#$;%^*+={}\\|\\\\&lt;&gt;,\'\"]{3,30}$</Property>
<Property name="RolenameJavaScriptRegEx">[\\S]{3,30}</Property>
<Property
name="RolenameJavaRegEx">^[^~!@#$;%^*+={}\\|\\\\&lt;&gt;,\'\"]{3,30}$</Property>
<Property name="ReadLDAPGroups">true</Property>
<Property name="WriteLDAPGroups">true</Property>
<Property name="EmptyRolesAllowed">true</Property>
<Property name="GroupSearchBase">ou=Groups,dc=wso2,dc=org</Property>
<Property name="GroupNameListFilter">(objectClass=groupOfNames)</Property>
<Property name="GroupEntryObjectClass">groupOfNames</Property>
<Property
name="GroupNameSearchFilter">(&amp;(objectClass=groupOfNames)(cn=?))</Property>
<Property name="GroupNameAttribute">cn</Property>
<Property name="MembershipAttribute">member</Property>
<Property name="UserRolesCacheEnabled">true</Property>
<Property name="UserDNPattern">uid={0},ou=Users,dc=wso2,dc=org</Property>
</UserStoreManager-->

The code block can be described as follows:

Property Name Description

ConnectionURL Connection URL to the ldap server. In the case of default LDAP in carbon, port
is mentioned in carbon.xml and a reference to that port is mentioned in the
above configuration.

ConnectionName This should be the DN (Distinguish Name) of the admin user in LDAP.

ConnectionPassword Password of the admin user.

passwordHashMethod Password Hash method when storing user entries in LDAP.


Allowed values are as follows:

SHA - Uses SHA digest method


MD5 - Uses MD 5 digest method
PLAIN_TEXT - Plain text passwords
In addition to above this supports all digest methods supported by http://docs.or
acle.com/javase/6/docs/api/java/security/MessageDigest.html.

UserNameListFilter Filtering criteria for listing all the user entries in LDAP.

Copyright WSO2 Inc. 2005-2014 47


WSO2 Carbon 4.1.0

UserEntryObjectClass Object Class used to construct user entries. In the case of default LDAP in
carbon, it is a custom object class defined with the name-'wso2Person'

UserSearchBase DN of the context under which user entries are stored in LDAP.

UserNameSearchFilter Filtering criteria for searching a particular user entry.

UserNameAttribute Attribute used for uniquely identifying a user entry. Users can be authenticated
using their email address, uid and etc .....

PasswordJavaScriptRegEx Policy that defines the password format.

UsernameJavaScriptRegEx The regular expression used by the font-end components for username
validation.

UsernameJavaRegEx A regular expression to validate usernames. By default, strings having length 5


to 30 non-empty characters are allowed.

RolenameJavaScriptRegEx The regular expression used by the font-end components for rolename
validation.

RolenameJavaRegEx A regular expression to validate rolenames. By default, strings having length 5


to 30 non-empty characters are allowed.

ReadLDAPGroups Specifies whether groups should be read from LDAP.

WriteLDAPGroups Specifies whether groups should be written to LDAP.

EmptyRolesAllowed Specifies whether underlying LDAP user store allows empty groups to be
created. In the case of ldap in carbon, the schema is modified such that empty
groups are allowed to be created. Usually LDAP servers do not allow to create
empty groups.

GroupSearchBase DN of the context under which user entries are stored in LDAP.

GroupNameListFilter Filtering criteria for listing all the group entries in LDAP.

GroupEntryObjectClass Object Class used to construct user entries.

GroupNameSearchFilter Filtering criteria for searching a particular group entry.

GroupNameAttribute Attribute used for uniquely identifying a user entry.

MembershipAttribute Attribute used to define members of LDAP groups.

UserRolesCacheEnabled This is to indicate whether to cache the role list of a user. By default it is 'true'.
Set it to 'falese' if user-roles are changed by external means and those changes
should be instantly reflected in the carbon instance.

UserDNPattern The patten for user's DN. It can be defined to improve the LDAP search. When
there are many user entries in the LADP, defining a "UserDNPattern" provides
more impact on performances as the LDAP does not have to travel through the
entire tree to find users.

Configuring External User Stores

The WSO2 User Manager authenticates users from different types of user stores and currently has the capability to
easily plugin to LDAP, Active Directory and JDBC to perform authentication.

Copyright WSO2 Inc. 2005-2014 48


WSO2 Carbon 4.1.0

All WSO2 Carbon based products can read and write users and roles from external LDAP user stores. You can
configure Carbon products to access LDAP or JDBC in one of the following modes.

Read-Only Mode
Read/Write Mode

Read-only mode

All WSO2 Carbon based products can read users and roles from external LDAP/Active Directory user stores. You
can configure Carbon products to read users/roles from your company LDAP. The "Read Only" mode does not write
any data into the LDAP.

Note that LDAP is used going forward to refer to both LDAP and ActiveDirectory servers.
Step 1 : Backup <carbon-home>/repository/conf/user-mgt.xml.

A sample file for LDAP user store is given below:

<UserManager>
<Realm>
<Configuration>
<AdminRole>admin</AdminRole>
<AdminUser>
<UserName>admin</UserName>
<Password>XXXXXX</Password>
</AdminUser>
<EveryOneRoleName>everyone</EveryOneRoleName>
<!-- By default users in thsi role sees the registry root -->
<Property name="dataSource">jdbc/WSO2CarbonDB</Property>
<Property
name="MultiTenantRealmConfigBuilder">org.wso2.carbon.user.core.config.multitenancy.Sim
pleRealmConfigBuilder</Property>
</Configuration>

<UserStoreManager
class="org.wso2.carbon.user.core.ldap.ReadOnlyLDAPUserStoreManager">
<Property name="ConnectionURL">ldap://localhost:10389</Property>
<Property name="ConnectionName">uid=admin,ou=system</Property>
<Property name="ConnectionPassword">admin123</Property>
<Property name="UserSearchBase">ou=system</Property>
<Property name="UserNameListFilter">(objectClass=person)</Property>
<Property name="UserNameAttribute">uid</Property>
<Property name="ReadLDAPGroups">false</Property>
<Property name="GroupSearchBase">ou=system</Property>
<Property name="GroupNameSearchFilter">(objectClass=groupOfNames)</Property>
<Property name="GroupNameAttribute">cn</Property>
<Property name="MembershipAttribute">member</Property>
</UserStoreManager>

</Realm>
</UserManager>

A sample file for Active Directory is given below:

Copyright WSO2 Inc. 2005-2014 49


WSO2 Carbon 4.1.0

<UserManager>
<Realm>
<Configuration>
<AdminRole>admin</AdminRole>
<AdminUser>
<UserName>admin</UserName>
<Password>XXXXXX</Password>
</AdminUser>
<EveryOneRoleName>everyone</EveryOneRoleName>
<!-- By default users in thsi role sees the registry root -->
<Property name="dataSource">jdbc/WSO2CarbonDB</Property>
<Property
name="MultiTenantRealmConfigBuilder">org.wso2.carbon.user.core.config.multitenancy.Sim
pleRealmConfigBuilder</Property>
</Configuration>

<!-- Active directory configuration follows -->


<UserStoreManager
class="org.wso2.carbon.user.core.ldap.ActiveDirectoryUserStoreManager">>
<Property name="ConnectionURL">ldap://10.100.1.211:389</Property>
<Property
name="ConnectionName">cn=Administrator,cn=users,dc=wso2,dc=lk</Property>
<Property name="ConnectionPassword">admin123</Property>
<Property name="UserSearchBase">cn=users,dc=wso2,dc=lk</Property>
<Property name="UserNameListFilter">(objectClass=person)</Property>
<Property name="UserNameAttribute">sAMAccountName</Property>
<Property name="ReadLDAPGroups">true</Property>
<Property name="GroupSearchBase">cn=users,dc=wso2,dc=lk</Property>
<Property name="GroupNameSearchFilter">(objectcategory=group)</Property>
<Property name="GroupNameAttribute">cn</Property>
<Property name="MembershipAttribute">member</Property>
</UserStoreManager>

</Realm>
</UserManager>

Copy the user-mgt-ldap.xml file and save it as <carbon-home>/repository/conf/user-mgt.xml. When


user-mgt-actdir.xmlyou are configuring for ActiveDirectory, do the same to .

Note the following in your file:

<UserStoreManager class="org.wso2.carbon.user.core.ldap.ReadOnlyLDAPUserStoreManager">

Step 2 : Find a valid user that resides in the Directory Server. For example, let's say a valid username is
"AdminSOA". Update the Admin user section of your LDAP configuration as follows. You don't have to update the
password element; leave it as it is.

<AdminUser>
<UserName>AdminSOA</UserName>
<Password>XXXXXX</Password>
</AdminUser>

Step 3 : Update the connection details to suit your Directory Server.

Copyright WSO2 Inc. 2005-2014 50


WSO2 Carbon 4.1.0

<Property name="ConnectionURL">ldap://localhost:10389</Property>

Step 4 : Obtain a user who has permission to read all users/attributes and perform searches on the Directory Server
from your LDAP administrator. For example, let's say the privileged user is "AdminLDAP" and password is
"2010#Avrudu". Now update the following sections of the realm configuration.

<Property name="ConnectionName">uid=AdminLDAP,ou=system</Property>
<Property name="ConnectionPassword">2010#Avrudu</Property>

Update the <Property name="UserSearchBase"> by giving the directory where the users are stored. LDAP searches
for users from this location.

Property name="UserSearchBase">ou=system</Property>

Step 5 : Set the attribute that you wish to be used as the username. The most common case is to use either "cn" or
"uid" as the username. If you are not sure what attribute is available in your LDAP, check with your LDAP
administrator.

<Property name="UserNameAttribute">uid</Property>

For Active Directory this is different.

<Property name="UserNameAttribute">sAMAccountName</Property>

Step 6 : This is the most basic configuration. For more advanced options like "external roles", jump to step 7.
Otherwise you are done! Now start your server and try to login as "AdminSOA". The password is the AdminSOA's
password in the LDAP server.
If you are unable to login, contact the WSO2 Carbon user group according to the contact details given under "comm
unity and support" section on the welcome page.
Step 7 : The realm can read roles from the Directory Server. It can read user/role mapping based on a backlink
attribute or membership (user list) attribute.
Step 7.1 : Reading roles based on a membership attribute. This is used by the ApacheDirectory server and
OpenLDAP.

<Property name="ReadLDAPGroups">false</Property>
<Property name="GroupSearchBase">ou=system</Property>
<Property name="GroupSearchFilter">(objectClass=groupOfNames)</Property>
<Property name="GroupNameAttribute">cn</Property>
<Property name="MembershipAttribute">member</Property>

Step 7.2 : Reading roles based on a backlink attribute. This is used by the Active Directory.

Copyright WSO2 Inc. 2005-2014 51


WSO2 Carbon 4.1.0

<Property name="ReadLDAPGroups">true</Property>
<Property name="GroupSearchBase">cn=users,dc=wso2,dc=lk</Property>
<Property name="GroupSearchFilter">(objectcategory=group)</Property>
<Property name="GroupNameAttribute">cn</Property>
<Property name="MemberOfAttribute">memberOf</Property>

The following table contains detail descriptions of each property:

Property Name Description

MaxUserNameListLength

ConnectionURL The connection URL to the database.

ConnectionName The username used to connect to the database.


This user must have permissions to read the user list and the user's
attributes.

ConnectionPassword Password of the connection username.

UserSearchBase Search base of users.


Note that different databases have different search bases.

UserNameListFilter The LDAP query that should be used to search for users.

UserNameAttribute Users can be authenticated using their email address, uid etc.
The name of the attribute considered as the username.

ReadLDAPGroups Indicates whether to read groups from the LDAP.


If this is set to 'false', none of the following attributes need to be set.

GroupSearchBase Search base for groups.

GroupNameListFilter Filtering criteria for listing all the group entries in LDAP.

GroupSearchFilter The LDAP query used to search for groups.

GroupNameAttribute The attribute to be treated as the group name.

MembershipAttribute Attribute that contains users.

UserRolesCacheEnabled This is to indicate whether to cache the role list of a user. By default it is
'true'. Set it to 'false', if user-roles are changed by external means and
those changes should be instantly reflected in the Carbon instance.

ReplaceEscapeCharactersAtUserLogin

Read/write mode

If you wish to connect to external LDAP user store such that only the user entries are written to external LDAP and
roles are not written to external LDAP, the only difference from the steps in section "Read-Only Mode" is the
following:

Copyright WSO2 Inc. 2005-2014 52


WSO2 Carbon 4.1.0

<UserStoreManager
class="org.wso2.carbon.user.core.ldap.ReadWriteLDAPUserStoreManager">

<CARBON_HOME>/repository/conf/user-mgt.xml file has a commented out configuration for external LDAP


user stores.
1. Enable the <ReadWriteLDAPUserStoreManager> element in the user-mgt.xml file. When it is enabled,
the user manager reads/writes into the LDAP user store.
2. The default configuration for external read/write LDAP user store in user-mgt.xml file is as follows. Change
the values according to your requirement.

<UserStoreManager
class="org.wso2.carbon.user.core.ldap.ReadWriteLDAPUserStoreManager">
<Property
name="ConnectionURL">ldap://localhost:${Ports.EmbeddedLDAP.LDAPServerPort}</Property>
<Property name="ConnectionName">uid=admin,ou=system</Property>
<Property name="ConnectionPassword">admin</Property>
<Property name="passwordHashMethod">SHA</Property>
<Property name="UserNameListFilter">(objectClass=person)</Property>
<Property name="UserEntryObjectClass">wso2Person</Property>
<Property name="UserSearchBase">ou=Users,dc=wso2,dc=org</Property>
<Property name="UserNameSearchFilter">(&amp;(objectClass=person)(uid=?))</Property>
<Property name="UserNameAttribute">uid</Property>
<Property name="PasswordJavaScriptRegEx">[\\S]{5,30}</Property>
<Property name="UsernameJavaScriptRegEx">[\\S]{3,30}</Property>
<Property
name="UsernameJavaRegEx">^[^~!@#$;%^*+={}\\|\\\\&lt;&gt;,\'\"]{3,30}$</Property>
<Property name="RolenameJavaScriptRegEx">[\\S]{3,30}</Property>
<Property
name="RolenameJavaRegEx">^[^~!@#$;%^*+={}\\|\\\\&lt;&gt;,\'\"]{3,30}$</Property>
<Property name="ReadLDAPGroups">true</Property>
<Property name="WriteLDAPGroups">true</Property>
<Property name="EmptyRolesAllowed">true</Property>
<Property name="GroupSearchBase">ou=Groups,dc=wso2,dc=org</Property>
<Property name="GroupNameListFilter">(objectClass=groupOfNames)</Property>
<Property name="GroupEntryObjectClass">groupOfNames</Property>
<Property
name="GroupNameSearchFilter">(&amp;(objectClass=groupOfNames)(cn=?))</Property>
<Property name="GroupNameAttribute">cn</Property>
<Property name="MembershipAttribute">member</Property>
<Property name="UserRolesCacheEnabled">true</Property>
<Property name="UserDNPattern">uid={0},ou=Users,dc=wso2,dc=org</Property>
</UserStoreManager>

Main elements of the configuration can be explained as follows:

Property Name Description

ConnectionURL Connection URL to the LDAP server. In the case of a default LDAP in Carbon, the
port is mentioned in the carbon.xml and a reference to that port is mentioned in
the above configuration.

ConnectionName This should be the DN (Distinguish Name) of the admin user in LDAP.

Copyright WSO2 Inc. 2005-2014 53


WSO2 Carbon 4.1.0

ConnectionPassword Password of the admin user.

passwordHashMethod Password Hash method when storing user entries in LDAP.

UserNameListFilter Filtering criteria for listing all the user entries in LDAP.

UserEntryObjectClass Object class used to construct user entries. In the case of a default LDAP in
Carbon, it is a custom object class defined with the name-'wso2Person'

UserSearchBase DN of the context under which user entries are stored in LDAP.

UserNameSearchFilter Filtering criteria for searching a particular user entry.

UserNameAttribute Attribute used for uniquely identifying a user entry. Users can be authenticated
using their email address, uid etc.

PasswordJavaScriptRegEx Policy that defines the password format.

UsernameJavaScriptRegEx The regular expression used by the font-end components for username validation.

UsernameJavaRegEx A regular expression to validate usernames. By default, strings having length 5 to


30 non-empty characters are allowed.

RolenameJavaScriptRegEx The regular expression used by the font-end components for rolename validation.

RolenameJavaRegEx A regular expression to validate rolenames. By default, strings having length 5 to 30


non-empty characters are allowed.

ReadLDAPGroups Specifies whether groups should be read from LDAP.

WriteLDAPGroups Specifies whether groups should be written to LDAP.

EmptyRolesAllowed Specifies whether underlying LDAP user store allows empty groups to be created.
In the case of LDAP in Carbon, the schema is modified such that empty groups are
allowed to be created. Usually LDAP servers do not allow to create empty groups.

GroupSearchBase DN of the context under which user entries are stored in LDAP.

GroupNameListFilter Filtering criteria for listing all the group entries in LDAP.

GroupEntryObjectClass Object Class used to construct user entries.

GroupNameSearchFilter Filtering criteria for searching a particular group entry.

GroupNameAttribute Attribute used for uniquely identifying a user entry.

MembershipAttribute Attribute used to define members of LDAP groups.

UserRolesCacheEnabled This is to indicate whether to cache the role list of a user. By default it is 'true'. Set it
to 'false' if user-roles are changed by external means and those changes should be
instantly reflected in the Carbon instance.

UserDNPattern The patten for user's DN. It can be defined to improve the LDAP search. When
there are many user entries in the LADP, defining a UserDNPattern provides
more impact on performances as the LDAP does not have to travel through the
entire tree to find users.

How to configure an external JDBC user store

Copyright WSO2 Inc. 2005-2014 54


WSO2 Carbon 4.1.0

All Carbon based products can work with external RDBMSs. You can configure Carbon to read users/roles from
your company RDBMS and even write to it. As a result, the user core is connected to two databases.

Carbon database where authorization information is stored in the internal Carbon database.
Your company database where users/roles resides.
So the user-mgt.xml file must contain details for two database connections. The connection details mentioned
earlier is used by the Authorization manager. If we specify another set of database connection details inside the Use
rStoreManager, it will read/write users to that database. Step by step guidelines for connecting to an external
JDBC user store in read-only mode is given below.
Step 1 : Back-up the <carbon-home>/repository/conf/user-mgt.xml file. A sample file for JDBC user
store (user-mgt-jdbc.xml) is available in <carbon-home>/repository/conf directory. Download the
relevant file and save it as <IS_HOME>/repository/conf/user-mgt.xml. Remove the comment in the
following section in your file if it is commented out:

<UserStoreManager class="org.wso2.carbon.user.core.jdbc.JDBCUserStoreManager">

Step 2 : Find a valid user that resides in the RDBMS. For example, say a valid username is "AdminSOA". Update
the Admin user section of your LDAP configuration as follows. You don't have to update the password element;
leave it as it is.

<AdminUser>
<UserName>AdminSOA</UserName>
<Password>XXXXXX</Password>
</AdminUser>

Step 3 : In user-mgt.xml file, add the passwordHashMethod property within the JDBCUserStoreManager.
For example,

<UserStoreManager class="org.wso2.carbon.user.core.jdbc.JDBCUserStoreManager">
<Property name="passwordHashMethod">SHA</Property>
...
</UserStoreManager>

The passwordHashMethod property specifies how the password should be stored, and usually has the values:

SHA - Uses SHA digest method.


MD5 - Uses MD 5 digest method.
PLAIN_TEXT - Plain text passwords.
In addition, it also supports all digest methods in http://docs.oracle.com/javase/6/docs/api/java/security/Mess
ageDigest.html.
Step 4 : Update connection details inside <UserStoreManager> class.

Step 5 : In user-mgt.xml file, under realm configuration, set the value of MultiTenantRealmConfigBuilder p
roperty to org.wso2.carbon.user.core.config.multitenancy.SimpleRealmConfigBuilder. For
example,

<Property
name="MultiTenantRealmConfigBuilder">org.wso2.carbon.user.core.config.multitenancy.Sim
pleRealmConfigBuilder</Property>

Copyright WSO2 Inc. 2005-2014 55


WSO2 Carbon 4.1.0

Step 6 : Add the JDBC driver to the classpath by dropping the JAR to <carbon-home>/repository/component
s/lib directory.

Step 7 : Edit the SQLs in user-mgt.xml file according to your requirements, and start the server.

Feature Management
This chapter contains the following information:
Introduction to Feature Management
Managing the Feature Repository
Installing Features via the UI
Installed Features
Installation History

The screenshots in this chapter may vary depending on the product you are installing.

Introduction to Feature Management

Each enterprise middleware product is a collection of reusable software units called features. Similarly, WSO2
Carbon consists of a collection of features where a single feature is a list of components and/or other feature. A
component in the Carbon platform is a single or a collection of OSGi bundles. Similar to a standard Jar file in Java, a
bundle is the modularization unit in OSGi.
Components in the Carbon platform add functionality to Carbon based products. For example, the statistics
component enables users to monitor system and service level statistics. This component contains two bundles. One
is the back-end bundle that collects, summarizes and stores statistics. The other is the front-end bundle, that
presents the data to the user through a user-friendly interface.
This component-based architecture of the WSO2 Carbon platform gives developers flexibility to build efficient and
lean products that best suit their unique business needs, simply by adding and removing components.

Provisioning WSO2 Carbon

Provisioning software is the act of placing an individual software application or a complete software stack onto a
target system. What we mean by provisioning WSO2 Carbon is installing/updating/uninstalling features to/from the
Carbon base platform on top of which the entire WSO2 product stack is developed. It is also possible to easily revert
to a previous feature configuration using the provisioning support.
Features can be easily installed to any WSO2 product using the WSO2 Carbon Feature Manager that comes with
the product. Feature manager is powered by Equinox P2 and allows you to connect to a remote or local P2
repository and get any feature installed into the product's runtime.
P2 can be used as a provisioning platform for any OSGi-based application. P2 has enabled easy provisioning
capabilities in WSO2 Carbon, thereby increasing the user-friendliness in building customized SOA products using
the Carbon platform. Users can download the WSO2 Carbon framework or any other WSO2 product and extend
them by simply installing various features. The WSO2 Feature Manager provides a convenient user interface to
perform common provisioning operations.
Managing the Feature Repository

1. Log on to the product's Management Console and select Features from the Configure menu.
For example,

Copyright WSO2 Inc. 2005-2014 56


WSO2 Carbon 4.1.0

2. The Repository Management tab allows you to view or modify feature management settings.

Adding a repository | Editing a repository | Enabling or disabling a repository | Deleting a repository

Adding a repository

1. To add a feature repository, click on the Add Repository link in the Manage Repositories pane.

2. Provide a convenient name and a URL of the repository. You can also add a repository downloaded on your
computer by giving the file path of the directory in the local option.

Copyright WSO2 Inc. 2005-2014 57


WSO2 Carbon 4.1.0

Tip
The official WSO2 Carbon features are available in a Equinox P2 repository at : http://dist.wso2.org/p2/carb
on/releases.
Equinox P2 provides provisioning technology for OSGi-based applications such as WSO2 Carbon.

Editing a repository

1. Select a repository to modify and click on the Edit link associated with it. For example,

2. You can specify a new name.

This page allows you to change the repository name only. If you want to change the URL, you need to
remove the old repository and add the new one.

Enabling or disabling a repository

Copyright WSO2 Inc. 2005-2014 58


WSO2 Carbon 4.1.0

To enable/disable a repository, click on the Enable or Disable link associated with the repository. For example:

By default, all the repositories are enabled. When you perform a provisioning operation, metadata and
artifacts are searched only from the enabled repositories.

Deleting a repository

1. Select a repository to delete and click on the Remove link associated with it.

2. Confirm your request.

Installing Features via the UI

The manual way of provisioning Carbon is dropping bundles and configuration files that belong to a feature. This
method is not recommended since it can cause errors. Besides, finding the exact set of components and
configurating files is a complex task. Components have inter-dependencies with other components. Some
components depend on specific versions of other components.
To overcome these issues, WSO2 has Equinox P2 integrated with Carbon. It enables user-friendly provisioning
capabilities by allowing users to download WSO2 Carbon or any other WSO2 product and simply extending them by
installing various features.
Follow the instructions below to install new features to any product of the WSO2 products stack:
1. Log on to the product's Management Console and select Features from the Configure menu.
For example,

Copyright WSO2 Inc. 2005-2014 59


WSO2 Carbon 4.1.0

2. The Feature Management page opens.


The Available Features tab allows you to search for available features in repositories. You can select a repository
from the drop-down menu. If there is no added repository, refer to section Managing the feature repository to add
one.

The following options can be selected.

Show only the latest versions

Some repositories contain multiple versions of features. If you are only interested in the latest versions, click the Sho
w only the latest versions option.

Group features by category

A feature category is a logical grouping of the features which constitute a particular Carbon-based product. The
"Group features by category" option enables you to easily view and select the entire list of features of a particular
product at once. For example, the features required to install WSO2 Data Services Server is grouped under the
'Data Service Server' feature category as shown below.

Copyright WSO2 Inc. 2005-2014 60


WSO2 Carbon 4.1.0

If you uncheck this option when finding features, you will see an uncategorized, flat feature list from which individual
features can be selected separately.
3. Once the repository and options are selected, click the Find Features button.
4. You will see a list of all the features. Select the ones you want to add by marking them using check-boxes.

To find a particular feature, you can use the search function. Enter the name of a feature (or a part of the
name) and press Enter.

This search will return only Available Features; excluding the ones already installed.

5. Once done, click Install.

Copyright WSO2 Inc. 2005-2014 61


WSO2 Carbon 4.1.0

6. The Install Details window appears.Verify the provided information and click Next.

7. Read and accept the terms of license agreement.

8. The installation process starts. It may take a few minutes to download the necessary components.
Once the installation process is complete, click Finish and restart the server for the changes to take effect.

Copyright WSO2 Inc. 2005-2014 62


WSO2 Carbon 4.1.0

9. You can see the functionality added by new features in the Management Console. For example, the Databases m
enu shows when Admin Console feature is installed.

View feature information

When features of a repository are loaded, you can install them or view the details of particular ones. To view the
details, click on the More Info link associated with each feature. For example,

When the link is clicked, the Feature Information window appears, with the following information:
Name
Identifier
Version
Provider
Description
Copyright
License Agreement
Familiarize yourself with the information and click Back to load the previous page. For example,

Copyright WSO2 Inc. 2005-2014 63


WSO2 Carbon 4.1.0

Installed Features

1. Log on to the product's Management Console and select Features from the Configure menu.
For example,

2. The Feature Management page opens.


The Installed Features tab allows you to browse through the list of installed features and select the ones you want
to uninstall. For example,

Copyright WSO2 Inc. 2005-2014 64


WSO2 Carbon 4.1.0

You can access additional information about a feature by clicking the More info link in the Actions column.

WSO2 Carbon supports back-end, front-end separation where you can manage multiple back-end servers using a
single front-end server. You can convert a given product either to a back-end server or to a front-end server. This
conversion can be performed using the Feature Manager user interface.
If you want to get only a back-end server, you have to uninstall all the front-end features.To do that, select Front-end
from the drop down menu as displayed in the example below.

This will list all the front-end features that are currently installed in the system. Pressing Uninstall will uninstall all the
front-end features in the current installation. The steps are similar if you want to convert your product in to a
front-end server.

Uninstalling features

1. Select features to uninstall by marking the relevant check-boxes. You can also select all/none features using the
appropriate links.

Copyright WSO2 Inc. 2005-2014 65


WSO2 Carbon 4.1.0

For example,

2. Once selected, click on Uninstall.

3. A page will appear containing details of the features to be uninstalled. Verify the information and click Next.

Note
A feature cannot be uninstalled from the system without uninstalling other features that depend on it, if any.

4. If successful, a message appears as Uninstallation Complete. Click Finish and restart the server to apply the
changes.

Installation History

1. Log on to the product's Management Console and select Features from the Configure menu.
For example,

Copyright WSO2 Inc. 2005-2014 66


WSO2 Carbon 4.1.0

2. The Installation History tab lists the history of provisioning operations performed on the system. Previous
configurations can be identified as previous states of the system. A state/configuration can be simply identified by
the set of installed features. When you perform a provisioning operation such as installing/uninstalling of features, a
system state/configuration change occurs.

You can revert the current configuration to a previous configuration. In this process, some features might get
installed and some uninstalled. When you click on a previous configuration, you will be able to see information as
shown in the following example.

Click Revert to revert the current configuration to a previous configuration or Back to return to the previous page
without any changes.
Server Roles for cApps

Copyright WSO2 Inc. 2005-2014 67


WSO2 Carbon 4.1.0

This chapter contains the following information:


Introduction to Server Roles
Adding a Server Role
Deleting a Server Role

Note
Screenshots in this section are taken using the WSO2 Carbon product. They may vary depending on the
product you are installing.

Introduction to Server Roles

A server-role is a parameter that is mentioned in the carbon.xml file (<PRODUCT_HOME>/repository/conf) of all


WSO2 Carbon based products. Each product has a different default ServerRoles property as follows:
WSO2 Application Server - "ApplicationServer"
WSO2 Business Activity Monitor - "BusinessActivityMonitor"
WSO2 Business Process Server - "BusinessProcessServer"
WSO2 Business Rules Server - "BusinessRulesServer"
WSO2 Data Services Server - "DataServicesServer"
WSO2 Enterprise Service Bus - "EnterpriseServiceBus"
WSO2 Gadget Server - "GadgetServer"
WSO2 Governance Registry - "GovernanceRegistry"
WSO2 Identity Server - "IdentityServer"
WSO2 Mashup Server - "MashupServer"
This property value is used for the deployment of WSO2 Carbon Applications.

What is a Carbon application

A Carbon Application, abbreviated as a cApp, is a collection of artifacts deployable on a Carbon instance. These
artifacts are usually java-based or xml configurations, designed differently for each product in the Carbon platform.
In a single Carbon-based solution, there can be numerous artifacts used, such as Axis2 services, data services,
synapse configurations, endpoints, proxy services, mediators, registry resources, BEPL workflows etc. Usually,
these artifacts are created in a development environment and then moved one by one into staging/production
environments. When moving a Carbon solution from one setup to the other, the user has to manually configure
these artifacts to build up the entire solution. This is a time-consuming process. Alternatively, bundling configuration
files and artifacts in a cApp makes it easy for users to port their Web service based solution from one environment to
another.
When a user deploys a cApp in a Carbon product, all its resources cannot be deployed in that particular product
instance. To specify which can and which cannot be deployed, the server-role property is used. When a cApp is
being deployed, it reads the ServerRoles property from the carbon.xml and deploys only the resources which match
the server-role values in there. Here is an example list of C-App resources that map to default server roles.
ApplicationServer - foo.aar, jax-wx.jar
EnterpriseServiceBus - proxy.xml
BusinessProcessServer - my_bpel.zip
GadgetServer - gadget.xml

Server roles manager

Server roles manager is a component to manage the server roles property for WSO2 Carbon based products. Due
to the functionality of the server roles manager, users do not have to manually modify the carbon.xml to include the

Copyright WSO2 Inc. 2005-2014 68


WSO2 Carbon 4.1.0

server-roles related to the product feature they have added to a Carbon product instance. As WSO2 Stratos, which
is the WSO2 Carbon based Cloud Middleware Platform, is introduced, the above action is not possible for a tenant
since the tenant user is remote to the server instance.
To overcome these difficulties, the server role manager is introduced. It stores both carbon.xml file's default product
roles as well as user/tenant specific server roles in the configuration registry. So, when a cApp is deployed in
Carbon, the cApp deployer checks for auto-mentioned server roles from the registry instead of the carbon.xml file.
In the server roles manager, the server-roles properties are of two types:
Default - All the server roles picked from that particular product instance's carbon.xml.
Custom - All other server roles added by the users.
Adding a Server Role

Follow the instructions below to add a new server role.


1. Log on to the product's Management Console and select Server Roles from the Configure menu.
For example,

2. The Server Roles page appears. Click on the Add New Server Role link.

3. The Add Custom Server Role window appears. Fill in the Role Name field and click the Add button.

Note
You can add any textual name as a server role without special characters except underscore.

4. The new server role is added and displayed in the server roles list.

Copyright WSO2 Inc. 2005-2014 69


WSO2 Carbon 4.1.0

Deleting a Server Role

Follow the instructions below to delete a server role.


1. Log on to the product's Management Console and select Server Roles from the Configure menu.

2. The Server Roles page appears. Chose the role you want to delete and click the Delete link associated with it.

3. Accept the confirmation.

You can't undo this operation once performed.

Users can even delete a default server role. Once deleted, the server role manager will not pick up the
deleted server role from the carbon.xml file, next time the server starts.

Transport Management

Copyright WSO2 Inc. 2005-2014 70


WSO2 Carbon 4.1.0

This chapter contains the following information:


Introduction to Transports
Carbon Transports

The screenshots used in this section may vary depending on the product you are using and the specific
configuration options.

Introduction to Transports

WSO2 Carbon is the base platform on which all WSO2 Java products are developed. Built on OSGi, WSO2 Carbon
encapsulates all major SOA functionality. It supports a variety of transports which make Carbon-based products
capable of receiving and sending messages over a multitude of transport and application-level protocols. This
functionality is implemented mainly in the Carbon core, which combines a set of transport-specific components to
load, enable, manage and persist transport related functionality and configurations.
All transports currently supported by WSO2 Carbon are directly or indirectly based on the Apache Axis2 transports
framework. This framework provides two main interfaces for each transport implementation.
org.apache.axis2.transport.TransportListener - Implementations of this interface should specify how incoming
messages are received and processed before handing them over to the Axis2 engine for further processing.
org.apache.axis2.transport.TransportSender - Implementations of this interface should specify how a
message can be sent out from the Axis2 engine.
Each transport implementation generally contains a transport receiver/listener and a transport sender, since they
use the interfaces above. The Axis2 transport framework enables the user to configure, enable and manage
transport listeners and senders independent to each other, without having to restart the server. For example, one
may enable only the JMS transport sender without having to enable JMS transport listener.
There are two main types of transports: blocking and non-blocking. In a blocking transport, the I/O threads get
blocked since the same worker thread that sends the request to the server will remain open to receive the
response, until messages are completely processed by the underlying Axis2 engine . However, in non-blocking
transports the worker thread that sends the request will not wait for the response and another thread will receive the
response. Thereby, non-blocking transports increase the performance of the server.
The transport management capability of WSO2 Carbon is provided by the following feature in the WSO2 feature
repository:
Name: WSO2 Carbon - Transport Management Feature
Identifier: org.wso2.carbon.transport.mgt.feature.group
If transport management capability is not included in your product by default, you can add it by installing the above
feature using the instructions given in section, Feature Management.
Carbon Transports

The following transport implementations are supported by default in the WSO2 Carbon platform:
HTTP Servlet Transport
HTTPS Servlet Transport
HTTP-NIO Transport
HTTPS-NIO Transport
VFS Transport
JMS Transport
MailTo Transport
TCP Transport
Local Transport
UDP Transport
FIX Transport
HTTP Servlet Transport

Copyright WSO2 Inc. 2005-2014 71


WSO2 Carbon 4.1.0

The transport receiver implementation of the HTTP transport is available in the Carbon core component. The
transport sender implementation comes from the Apache Axis2 transport module. This transport is shipped with
WSO2 Carbon and all WSO2 Carbon-based products, which use this transport as the default transport, except
WSO2 ESB. The two classes which implement the listener and sender APIs are org.wso2.carbon.core.trans
ports.http.HttpTransportListener and org.apache.axis2.transport.http.CommonsHTTPTransp
ortSender respectively.

This is a blocking HTTP transport implementation, meaning that I/O threads get blocked while received
messages are processed completely by the underlying Axis2 engine.

In transport parameter tables, literals displayed in italic mode under the "Possible Values" column should be
considered as fixed literal constant values. Those values can be directly put in transport configurations.

Transport receiver parameters

Parameter Description Required Possible Default


Name Values Value

port The port number on which this transport receiver should listen for Yes A
incoming messages. positive
integer
less than
65535

proxyPort When used, this transport listener will accept messages arriving No A
through a HTTP proxy server which listens on the specified proxy positive
port. Apache mod_proxy should be enabled in the proxy server. integer
All the WSDLs generated will contain the proxy port value as the less than
listener port. 65535

When using org.wso2.carbon.core.transports.http.HttpTransportListener as the transport receiver


implementation, HTTP servlet transport should be configured in the $PRODUCT_HOME/conf/transports.xml file
. The transport class that should be specified in the transports.xml file is as follows:

org.wso2.carbon.server.transports.http.HttpTransport

This servlet transport implementation can be further tuned up using the following parameters.

Parameter Name Description Required Possible Default


Values Value

port The port over which this transport Yes A positive


receiver listens for integer less
incoming messages. than 65535

Copyright WSO2 Inc. 2005-2014 72


WSO2 Carbon 4.1.0

proxyPort When used, this transport listener No A positive


will accept messages integer less
arriving through a HTTP proxy server than 65535
which listens on the
specified proxy port. Apache mod_pr
oxy should be enabled
on the proxy server. All the WSDLs
generated will contain the
proxy port value as the listener port.

maxHttpHeaderSize The maximum size of the HTTP No A positive 4096


request and response header integer
in bytes.

maxThreads The maximum number of worker No A positive 40


threads created by the receiver integer
to handle incoming requests. This
parameter largely determines
the number of concurrent
connections that can be handled by
the transport.

enableLookups Use this parameter to enable DNS No true, false true


lookups in order to return the
actual host name of the remote
client. Disabling DNS lookups
at transport level generally improves
performance.

disableUploadTimeout This flag allows the servlet container No true, false true
to use a different, longer
connection timeout while a servlet is
being executed, which in
the end allows either the servlet a
longer amount of time to
complete its execution, or a longer
timeout during data upload.

clientAuth Set to true if you want the SSL stack No true, false, want false
to require a valid certificate
chain from the client before
accepting a connection. Set to want
if you want the SSL stack to request
a client Certificate, but not
fail if one is not present. A false
value (which is the default) will
not require a certificate chain unless
the client requests a resource
protected by a security constraint
that uses CLIENT-CERT
authentication.

Copyright WSO2 Inc. 2005-2014 73


WSO2 Carbon 4.1.0

maxKeepAliveRequests The maximum number of HTTP No -1 or a n y 100


requests which can be pipelined positive integer
until the connection is closed by the
server. Setting this attribute
to 1 will disable HTTP/1.0 keep-alive,
as well as HTTP/1.1 keep-alive
and pipelining. Setting this to -1 will
allow an unlimited amount of
pipelined or keep-alive HTTP
requests.

acceptCount The maximum queue length for No A positive 10


incoming connection requests when integer
all possible request processing
threads are in use. Any requests
received when the queue is full will
be refused.

compression Use this parameter to enable content No on, off, force off
compression and save server
bandwidth.

noCompressionUserAgents Indicate a list of regular expressions No A c o m m a empty string


matching user-agents of HTTP separated list of
clients for which compression should
not be used, because these regular
clients, although they do advertise expressions
support for the feature, have a
broken implementation.

compressableMimeType Use this parameter to indicate a list No A c o m m a text/html,text


of MIME types for which HTTP separated list of /xml,text/plain
compression may be used.
valid mime
types

This is only a subset of all the supported parameters. The servlet HTTP transport uses the org.apache.catalina.conn
ector.Connector implementation from Apache Tomcat. So the servlet HTTP transport actually accepts any
parameter accepted by the connector implementation. Please refer to Apache Tomcat's connector configuration
reference (http://tomcat.apache.org/tomcat-5.5-doc/config/http.html) for more information and a complete list of
supported parameters.

Transport sender parameters

Parameter Name Description Requried Possible Default


Values Value

PROTOCOL The version of HTTP protocol to be used for outgoing No HTTP/1.0, HTTP/1.1
messages. HTTP/1.1

Transfer-Encoding Effective only when the HTTP version is 1.1 (i.e., the No chunked Not
value of the PROTOCOL parameter should be Chunked
HTTP/1.1). Use this parameter to enable chunking
support for the transport sender.

SocketTimeout The socket timeout value in milliseconds, for out bound No A positive 60000
connections. integer ms

Copyright WSO2 Inc. 2005-2014 74


WSO2 Carbon 4.1.0

ConnectionTimeout The connection timeout value in milliseconds, for out No A positive 60000
bound connections. integer ms

OmitSOAP12Action Set this parameter to "true" if you need to disable the No true, false false
SOAPAction for SOAP 1.2 messages.

HTTPS Servlet Transport

Similar to the HTTP transport, the HTTPS transport consists of a receiver implementation which comes from the
Carbon core component and a sender implementation which comes from the Apache Axis2 transport module. In
fact, this transport uses exactly the same transport sender implementation as the HTTP transport. So the two
classes that should be specified in the configuration are org.wso2.carbon.core.transports.http.HttpsTr
ansportListener and org.apache.axis2.transport.http.CommonsHTTPTransportSender for the
receiver and sender in the specified order. The configuration parameters associated with the receiver and the
sender are the same as in HTTP transport. This is also a blocking transport implementation.
However, when using the following class as the receiver implementation, we need to specify the servlet HTTPS
transport configuration in the transport's XML file.
org.wso2.carbon.core.transports.http.HttpsTransportListener
The class that should be specified as the transport implementation is org.wso2.carbon.server.transports.
http.HttpsTransport. In addition to the configuration parameters supported by the HTTP servlet transport,
HTTPS servlet transport supports the following configuration parameters:

In transport parameter tables, literals displayed in italic mode under the "Possible Values" column should be
considered as fixed literal constant values. Those values can be directly put in transport configurations.

Parameter Description Requried Possible Values Default


Name Value

sslProtocol Transport level security protocol to be used. No TLS, SSL TLS

keystore Path to the keystore which should be used for Yes A valid file path to a
encryption/decryption. keystore file

keypass Password to access the specified keystore. Yes A valid password

Similar to the servlet HTTP transport, this transport is also based on Apache Tomcat's connector implementation.
Please refer Tomcat connector configuration reference for a complete list of supported parameters.
HTTP-NIO Transport

HTTP-NIO transport is a module of the Apache Synapse project. Apache Synapse (as well as the WSO2 ESB)
ships the HTTP-NIO transport as the default HTTP transport implementation. The two classes that implement the
receiver and sender APIs are org.apache.synapse.transport.nhttp.HttpCoreNIOListener and org.ap
ache.synapse.transport.nhttp.HttpCoreNIOSender respectively. These classes are available in the JAR
file named synapse-nhttp-transport.jar. This non-blocking transport implementation is one of the secrets
behind the superior performance figures of the WSO2 ESB. The transport implementation is based on Apache
HTTP Core - NIO and uses a configurable pool of non-blocking worker threads to grab incoming HTTP messages
off the wire.

HTTP relay transport

Message Relay in older versions of Carbon was simply a message builder-formatter pair. You engage it on a
per-content basis. Once engaged for a given content type, messages with that content type are streamed through
Carbon. It ran on same old NHTTP transport.

Copyright WSO2 Inc. 2005-2014 75


WSO2 Carbon 4.1.0

The Relay transport in newer versions of Carbon (starting from version 4.0.0) is an entire HTTP transport
implementation based on HTTP Core NIO. This can be used as an alternative to the NHTTP transport. It doesn't
really care about the content type and simply streams all received messages through. It's as if the old Message
Relay was engaged on all possible content types. The new transport also has a simpler and cleaner model for
forwarding messages back and forth.
To enable this, remove the comment of the relevant HTTP transport entries in the axis2.xml. Also, comment out
the usual settings for NHTTP transport receiver and sender.

Transport receiver parameters

In transport parameter tables, literals displayed in italic mode under the "Possible Values" column should be
considered as fixed literal constant values. Those values can be directly put in transport configurations.

Parameter Description Required Possible Values Default


Name Value

port The port on which this transport No A positive integer less than 8280
receiver should listen for incoming 65535
messages.

non-blocking Setting this parameter to true is Yes true


vital for reliable messaging and a
number of other scenarios to work
properly.

bind-address The address of the interface to No A host name or an IP address 127.0.0.1


which the transport listener should
bind.

hostname The host name of the server to be No A host name or an IP address localhost
displayed in service EPRs, WSDLs
etc. This parameter takes effect
only when the WSDLEPRPrefix
parameter is not set.

WSDLEPRPrefix A URL prefix which will be added to No A URL of the form


all service EPRs and EPRs in <protocol>://<hostname>:<port>/
WSDLs etc.

Transport sender parameters

Parameter Name Description Required Possible Default


Values Value

http.proxyHost If the outgoing messages should be sent through No A host name or


an HTTP proxy server, use this parameter to an IP address
specify the target proxy.

http.proxyPort The port through which the target proxy accepts No A positive
HTTP traffic. integer less than
65535

http.nonProxyHosts The list of hosts to which the HTTP traffic should No A list of host
be sent directly without going through the proxy. names or IP
addresses
separated by '|'

Copyright WSO2 Inc. 2005-2014 76


WSO2 Carbon 4.1.0

non-blocking Setting this parameter to true is vital for reliable Yes true
messaging and a number of other scenarios to
work properly.

HTTPS-NIO Transport

HTTPS-NIO transport is also a module that comes from the Apache Synapse code base. The receiver class is
named as follows:
org.apache.synapse.transport.nhttp.HttpCoreNIOSSLListener
The sender class is named as follows:
org.apache.synapse.transport.nhttp.HttpCoreNIOSSLSender
As far as the actual implementation of the transport is concerned, these two classes simply extend the HTTP-NIO
implementation by adding SSL support to it. Therefore, they support all the configuration parameters supported by
the HTTP-NIO receiver and sender. In addition to that, both HTTPS-NIO listener and the HTTPS-NIO sender
support the following two parameters. The above mentioned classes are available in the synapse-nhttp-transp
ort.jar bundle.

Transport Parameters (Common to both receiver and the sender):

Parameter Description Requried Possible Values Default


Name Value

keystore The default keystore to be used Yes <parameter name="keystore">


by the receiver or the sender <KeyStore>
should be specified here along <Location>lib/identity.jks</Location>
with its related parameters as an <Type>JKS</Type>
XML fragment. The path to the <Password>password</Password>
keystore file, its type and the <KeyPassword>password</KeyPassword>
passwords to access the
keystore should be stated in the </KeyStore>
XML. The keystore would be </parameter>
used by the transport to initialize
a set of key managers.

truststore The default trust store to be Yes <parameter name="truststore">


used by the receiver or the <TrustStore>
sender should be specified here <Location>lib/identity.jks</Location>
along with its related parameters <Type>JKS</Type>
as an XML fragment. The <Password>password</Password>
location of the trust store file, its </TrustStore>
type and the password should </parameter>
be stated in the XML body. The
truststore is used by the
transport to initialize a set of
trust managers.

The HTTPS NIO transport sender supports the concept of custom SSL profiles. An SSL profile is a user defined
keystore-truststore pair. Such an SSL profile can be associated with one or more target servers. When the HTTPS
sender connects to a target server, it will use the SSL profile associated with the target server. If no custom SSL
profiles are configured for the target server, the default keystore-truststore pair will be used. Using this feature the
NIO HTTPS sender can connect to different target servers using different certificates and identities. The following
table shows how to configure custom SSL profiles. The given example only contains a single SSL profile, but there
can be as many profiles as required.

Copyright WSO2 Inc. 2005-2014 77


WSO2 Carbon 4.1.0

Parameter Name Description Requried Possible Values Default


Value

customSSLProfiles Define one or more custom SSL No <parameter


profiles and associate them with name="customSSLProfiles>
target servers. Each profile must <profile>
be associated with at least one <servers>www.test.org:80,
target server. If a profile should www.test2.com:9763</servers>
be associated with multiple target <KeyStore>
<Location>/path/to/identity/store
servers, the server list should be </Location>
specified as a comma separated <Type>JKS</Type>
list. A target server is identified <Password>password</Password>
by a host-port pair.
<KeyPassword>password
</KeyPassword>
</KeyStore>
<TrustStore>
<Location>path/to/trust/store
</Location>
<Type>JKS</Type>
<Password>password</Password>

</TrustStore>
</profile>
</parameter>

VFS Transport

VFS (Virtual File System) transport implementation is a module which belongs to the Apache Synapse project.
The following classes implement the listener and sender APIs.
org.apache.synapse.transport.vfs.VFSTransportListener
org.apache.synapse.transport.vfs.VFSTransportSender
The necessary classes can be found in the synapse-vfs-transport.jar file. Unlike the transports described
previously, VFS transport does not have any global parameters to be configured. Rather, it has a set of service level
parameters that needs to be specified for each service. VFS transport implementation is mainly used and mostly
effective in the WSO2 ESB.
Starting from Carbon version 4.0.0, VFS transport supports the FTPS protocol. Configuration is identical to other
protocols with the only difference being the URL prefixes.
The VFS transport implementation is based on Apache Commons VFS implementation. Therefore commons-vfs.j
ar file should be included in the Carbon classpath to enable the VFS transport.

Since VFS transport deals with file operations, there are instances that these can fail due to unavailability of some
resource. In such an instance, the VFS transport is equipped with the following fault-handling mechanism.
When a failure occurs in a file object, that will be marked as a fail record and will be moved to location (configured
by the user) where move error file objects are kept. The failed record will be maintained inside a text file (file name is
configurable) and the location of that file will be provided by the user. When the next polling iteration is going on, it
will check the file against the failed record and if the file is a failed record, it will skip processing and schedule a
move task to move that file (the retry duration of the file move task can be configured). It's handled this way because
it is a random failure in the move operation.

VFS service level parameters

In transport parameter tables, literals displayed in italic mode under the "Possible Values" column should be

Copyright WSO2 Inc. 2005-2014 78


WSO2 Carbon 4.1.0

considered as fixed literal constant values. Those values can be directly put in transport configurations.

Parameter Name Description Required Possible Values Default Value

transport.vfs. The file URL from Yes A valid file URL


FileURI where the input files of the form file://
should be fetched. file://<path>

transport.vfs. Content type of the files Yes A valid content


ContentType transferred over the transport. type for the
files (e.g., text/xml)

transport.vfs. If the VFS listener No A regular


FileName should read only a expression to
Pattern subset of all the files select files by
available in the name
specified file URI (e.g.,*\.xml)
location, this parameter
can be used to select
those files by name
using a regular
expression.

transport. The polling interval in No A positive integer


PollInterval milliseconds for the
transport receiver to
poll the file URI
location.

transport.vfs. Action to perform No MOVE, DELETE


ActionAfter over the files after DELETE
Process processed by
the transport.

transport.vfs. Action to perform No MOVE, DELETE


ActionAfter over the files after DELETE
Failure processed by
the transport.

transport.vfs. The location to Required if A valid file URI


MoveAfter move the files ActionAfterProcess
Process after processing.
is MOVE

transport.vfs. The location to Required if A valid file URI


MoveAfter move the files ActionAfterFailure
Failure after a failure is MOVE
occurs.

transport.vfs. The location to No A valid file URI


ReplyFileURI which reply files
should be written
by the transport.

transport.vfs. The name for reply files No A valid file response.xml


ReplyFile written by the transport. name
Name

Copyright WSO2 Inc. 2005-2014 79


WSO2 Carbon 4.1.0

transport.vfs. The pattern/format No A valid timestamp


Move of the timestamps pattern
Timestamp added to file names (e.g., yyyy-MM-
Format as prefixes when dd'T'HH:mm
moving files (See :ss.SSSZ)
the API documentation
of java.text.
SimpleDateFormat
for details).

transport.vfs. If files should be transferred No true, false false


Streaming in streaming mode or not.

transport.vfs. Reconnect timeout No A positive 30 sec


Reconnect value in seconds integer
Timeout to be used in
case of an error
when transferring
files.

transport.vfs. Maximum number of No A positive 3


MaxRetry retry attempts to integer
Count carry out in case
of errors.

transport.vfs. When writing the No true, false false


Append response to a file,
if the response
should be appended
to the response file
this parameter
should be set to
t r u e .

By default the
response file will
be completely
overwritten.

transport.vfs. New destination No A valid file URI


MoveAfter to move the
FailedMove failed file.

transport.vfs. The file name to maintain No A valid file name vfs-move-


Failed the list of failure files. failed-
Records records.
FileName properties

transport.vfs. The destination of the No A folder URI repository


Failed failed file. /conf/
Records
F i l e
Destination

Copyright WSO2 Inc. 2005-2014 80


WSO2 Carbon 4.1.0

transport.vfs. When adding a record No A valid timestamp dd-MM-


Move to the failed file, pattern (eg: yyyy- yyyy
Failed entries are logged MM-dd'T'HH:mm: HH:mm
Record a s : ss.SSSZ) :ss
Timestamp file_name
Format time_stamp.
This will configure
the time stamp
format.

transport.vfs. The time in milli No A positive 3000 milli


Failed second for the integer seconds
Record move task to wait
Next until next retry.
Retry
Duration

You can find a VFS transport implementation in this tutorial: http://wso2.org/library/tutorials/2011/01/sftp-file-transer-


wso2-esb
JMS Transport

JMS (Java Message Service) transport implementation also comes from the WS-Commons Transports project. All
the relevant classes are packed into the axis2-transport-jms-<version>.jar and the following classes act
as the transport receiver and the sender respectively.
org.apache.axis2.transport.jms.JMSListener
org.apache.axis2.transport.jms.JMSSender
The JMS transport implementation requires an active JMS server instance to be able to receive and send
messages. We recommend using Apache ActiveMQ JMS server, but other implementations such as Apache Qpid
and Tibco are also supported. You also need to put the client JARs for your JMS server in Carbon classpath. In
case of Apache ActiveMQ, you need to put the following JARs in the classpath:
activemq-core.jar
geronimo-j2ee-management_1.0_spec-1.0.jar
geronimo-jms_1.1_spec-1.1.1.jar
These JAR files can be obtained by downloading the latest version of Apache ActiveMQ (version 5.2.0 is
recommended). Extract the downloaded archive and find the required dependencies in the $ACTIVEMQ_HOME/lib
directory. You need to copy these JAR files over to $CARBON_HOME/repository/components/lib directory for
Carbon to be able to pick them up at run-time.
Configuration parameters for JMS receiver and the sender are XML fragments that represent JMS connection
factories. A typical JMS parameter configuration would look like this:

<parameter name="myTopicConnectionFactory">
<parameter
name="java.naming.factory.initial">org.apache.activemq.jndi.ActiveMQInitialContextFact
ory</parameter>
<parameter name="java.naming.provider.url">tcp://localhost:61616</parameter>
<parameter
name="transport.jms.ConnectionFactoryJNDIName">TopicConnectionFactory</parameter>
<parameter name="transport.jms.ConnectionFactoryType">topic</parameter>
</parameter>

This is a bare minimal JMS connection factory configuration, which consists of four connection factory parameters.
JMS connection factory parameters are described in detail below.

Copyright WSO2 Inc. 2005-2014 81


WSO2 Carbon 4.1.0

JMS connection factory parameters

In transport parameter tables, literals displayed in italic mode under the "Possible Values" column should be
considered as fixed literal constant values. Those values can be directly put in transport configurations.

Parameter Name Description Required Possible Valu

java.naming.factory.initial JNDI initial context factory class. The class must Yes A valid class n
implement the java.naming.spi.InitialCo
ntextFactory interface.

java.naming.provider.url URL of the JNDI provider. Yes A valid URL

java.naming.security.principal JNDI Username. No

java.naming.security.credentials JNDI password. No

transport.Transactionality Desired mode of transactionality. No none, local, jta

transport.UserTxnJNDIName JNDI name to be used to require user transaction. No

transport.CacheUserTxn Whether caching for user transactions should be No true, false


enabled or not.

transport.jms.SessionTransacted Whether the JMS session should be transacted or No true, false


not.

transport.jms.SessionAcknowledgement JMS session acknowledgment mode. No AUTO_ACKN


CLIENT_ACK
DUPS_OK_AC
SESSION_TR

transport.jms.ConnectionFactoryJNDIName The JNDI name of the connection factory. Yes

transport.jms.ConnectionFactoryType Type of the connection factory. No queue, topic

transport.jms.JMSSpecVersion JMS API version. No 1.1, 1.0.2b

transport.jms.UserName The JMS connection username. No

transport.jms.Password The JMS connection password. No

transport.jms.Destination The JNDI name of the destination. No

transport.jms.DestinationType Type of the destination. No queue, topic

transport.jms.DefaultReplyDestination JNDI name of the default reply destination. No

transport.jms.DefaultReplyDestinationType Type of the reply destination. No queue, topic

transport.jms.MessageSelector Message selector implementation. No

transport.jms.SubscriptionDurable Whether the connection factory is subscription No true, false


durable or not.

transport.jms.DurableSubscriberName Name of the durable subscriber. Yes if the


subscription
durable is
turned on

Copyright WSO2 Inc. 2005-2014 82


WSO2 Carbon 4.1.0

transport.jms.PubSubNoLocal Whether the messages should be published by No true, false


the same connection they were received.

transport.jms.CacheLevel JMS resource cache level. No none, conne


consumer, pro

transport.jms.ReceiveTimeout Time to wait for a JMS message during polling. No Number of


Set this parameter value to a negative integer to wait
wait indefinitely. Set to zero to prevent waiting.

transport.jms.ConcurrentConsumers Number of concurrent threads to be started to No Any positive


consume messages when polling. topics this mu

transport.jms.MaxConcurrentConsumers Maximum number of concurrent threads to use No Any positive


during polling. topics this mu

transport.jms.IdleTaskLimit The number of idle runs per thread before it dies No Any positive in
out.

transport.jms.MaxMessagesPerTask The maximum number of successful message No Any positive


receipts per thread. to indicate infi

transport.jms.InitialReconnectDuration Initial reconnection attempts duration in No Any positive in


milliseconds.

transport.jms.ReconnectProgressFactor Factor by which the reconnection duration will be No Any positive in


increased.

transport.jms.MaxReconnectDuration Maximum reconnection duration in milliseconds. No

JMS transport implementation has some parameters that should be configured at service level, in other words in
service XML files of individual services.

Service level JMS configuration parameters

Parameter Name Description Required Possible Values Default


Value

transport.jms.ConnectionFactory Name of the JMS connection No A name of an already default


factory the service should use. defined connection
factory

transport.jms.PublishEPR JMS EPR to be published in the No A JMS EPR


WSDL.

MailTo Transport

The polling MailTo transport supports sending messages (E-Mail) over SMTP and receiving messages over POP3
or IMAP. This transport implementation is available as a module of the WS-Commons Transports project. The
receiver and sender classes that should be included in the Carbon configuration to enable the MailTo transport are o
rg.apache.axis2.transport.mail.MailTransportListener and org.apache.axis2.transport.mai
l.MailTransportSender respectively. The JAR consisting of the transport implementation is named axis2-tra
nsport-mail.jar.

The mail transport receiver should be configured at service level. That is each service configuration should explicitly
state the mail transport receiver configuration. This is required to enable different services to receive mails over
different mail accounts and configurations. However, transport sender is generally configured globally so that all
services can share the same transport sender configuration.

Copyright WSO2 Inc. 2005-2014 83


WSO2 Carbon 4.1.0

Service level transport receiver parameters

The MailTo transport listener implementation can be configured by setting the parameters described in JavaMail API
documentation. For IMAP related properties, refer the documentation for com.sum.mail.imap package. For POP3
properties please refer the documentation for com.sun.mail.pop3 package. Apart from the parameters describes in
JavaMail API documentation, the MailTo transport listener supports the following transport parameters.

In transport parameter tables, literals displayed in italic mode under the "Possible Values" column should be
considered as fixed literal constant values. Those values can be directly put in transport configurations.

Parameter Name Description Required Possible Default


Values Value

transport.mail.Address The mail address from which Yes A valid


this service should fetch e-mail
incoming mails. address

transport.mail.Folder The mail folder in the server No A valid inbox


from which the listener should mail folder if
fetch incoming mails. folder that is
name available
(e.g., or else
inbox) the root
folder

transport.mail.Protocol The mail protocol to be used to No pop3, imap


receive messages. imap

transport.mail.PreserveHeaders A comma separated list of mail No A comma


header names that this receiver separated
should preserve in all incoming list
messages.

transport.mail.RemoveHeaders A comma separated list of mail No A comma


header names that this receiver separated
should remove from incoming list
messages.

transport.mail.ActionAfterProcess Action to perform on the mails No MOVE, DELETE


after processing them. DELETE

transport.mail.ActionAfterFailure Action to perform on the mails No MOVE, DELETE


after a failure occurs while DELETE
processing them.

transport.mail.MoveAfterProcess Folder to move the mails after Required if A valid


processing them. ActionAfterProcess m a i l
is MOVE folder
name

transport.mail.MoveAfterFailure Folder to move the mails after Required if A valid


encountering a failure. ActionAfterFailure m a i l
is MOVE folder
name

Copyright WSO2 Inc. 2005-2014 84


WSO2 Carbon 4.1.0

transport.mail.ProcessInParallel Whether the receiver should No true, false false


process incoming mails in
parallel or not (works only if the
mail protocol supports that - for
example, IMAP).

transport.ConcurrentPollingAllowed Whether the receiver should No true, false false


poll for multiple messages
concurrently.

transport.mail.MaxRetryCount Maximum number of retry Yes A positive


operations to be performed integer
when fetching incoming mails.

transport.mail.ReconnectTimeout The reconnect timeout in Yes A positive


milliseconds to be used when integer
fetching incoming mails.

Global Transport Sender Parameters

For a list of parameters supported by the MailTo transport sender, refer the API documentation for JavaMail
com.sun.mail.smtp package. In addition to the parameters described there, the MailTo transport sender supports the
following parameters.

Parameter Name Description Required Possible Default


Values Value

transport.mail.SMTPBccAddresses If one or more e-mail addresses need to No A comma


be specified as BCC addresses for separated
outgoing mails, this parameter can be list of
used. e-mail
addresses

transport.mail.Format Format of the outgoing mail. No Text, Multi Text


part

TCP Transport

The TCP transport implementation is in the Apache WS-Commons Transports project. The two classes that act as
the transport listener and the sender are org.apache.axis2.transport.tcp.TCPServer and org.apache.
axis2.transport.tcp.TCPTransportSender respectively. In order to use the transport axis2-transport-
tcp.jar should be added to the Carbon classpath.

Transport receiver parameters

Parameter Description Requried Possible Values Default


Name Value

port The port on which the TCP server should listen for No A positive integer less 8000
incoming messages than 65535

hostname The host name of the server to be displayed in No A valid host name or
WSDLs etc an IP address

Transport sender parameters

The TCP transport sender does not accept any configuration parameters as of now.

Copyright WSO2 Inc. 2005-2014 85


WSO2 Carbon 4.1.0

To enable the TCP transport for samples, simply open the repository/conf/axis2.xml file in a text editor and
add the following transport receiver configuration and sender configuration. TCP transport module is shipped with
WSO2 ESB by default.

<transportReceiver name="tcp">
<parameter name="transport.tcp.port">6060</parameter>
</transportReceiver>

<transportSender name="tcp"/>

If you wish to use the sample Axis2 client to send TCP messages, you have to remove the comment of the TCP
transport sender configuration in the following file:

samples/axis2Client/client_repo/conf/axis2.xml
Local Transport

Apache Axis2's local transport implementation is used to make internal service calls and transfer data within the
Axis2 instance. The following class implements the sender API:
org.apache.axis2.transport.local.LocalTransportSender
The transport does not have a receiver implementation as of now.
It provides an opportunity for fast in-VM service call.

To use this transport, configure an endpoints with the local:// prefix. For example, to make an in-VM call
to the HelloService, use local://HelloService.

Configuring a local transport with WSO2 products

Shown below is how to configure a local transport with any WSO2 Carbon-based product.
1. In the carbon.xml file at location <PRODUCT_HOME>/repository/conf, an endpoint is available as follows by
default.

<ServerURL>local://services/&lt;/ServerURL>

2. In the axis2.xml file at location <PRODUCT_HOME>/repository/conf/axis2, there is a transport sender named


'local' specified as follows:

<transportSender name="local"
class="org.apache.axis2.transport.local.LocalTransportSender"/>

It has to be replaced with the following sender/receiver pair.

<transportReceiver name="local"
class="org.wso2.carbon.core.transports.local.CarbonLocalTransportReceiver"/>
<transportSender name="local"
class="org.wso2.carbon.core.transports.local.CarbonLocalTransportSender"/>

For more information about transports, refer to Introduction to Transports.


UDP Transport

Copyright WSO2 Inc. 2005-2014 86


WSO2 Carbon 4.1.0

The UDP transport implementation is in the Apache WS-Commons Transports project. The following classes
implement the Axis2 transport listener and sender APIs respectively.
org.apache.axis2.transport.udp.UDPListener
org.apache.axis2.transport.udp.UDPSender
The axis2-transport-udp.jar archive file contains the above implementation classes.
To enable the UDP transport for samples, simple open the file repository/conf/axis2.xml in a text editor and add the
following transport configurations. UDP transport component is shipped with the WSO2 ESB by default.

<transportReceiver name="udp"/>
<transportSender name="udp"/>

If you wish to use the sample Axis2 client to send UDP messages, you have to uncomment the UDP transport
sender configuration in the samples/axis2Client/client_repo/conf/axis2.xml file.
FIX Transport

FIX (Financial Information eXchang) transport implementation is a module developed under the Apache Synapse
project. This transport is mainly used with WSO2 ESB in conjunction with proxy services. The following class acts as
the transport receiver:
org.apache.synapse.transport.fix.FIXTransportListener
The org.apache.synapse.transport.fix.FIXTransportSender acts as the transport sender
implementation. These classes can be found in the synapse-fix-transport.jar file. The transport
implementation is based on Quickfix/J open source FIX engine. Therefore, the following additional dependencies are
required to enable the FIX transport.
mina-core.jar
quickfixj-core.jar
quickfixj-msg-fix40.jar
quickfixj-msg-fix41.jar
quickfixj-msg-fix42.jar
quickfixj-msg-fix43.jar
quickfixj-msg-fix44.jar
slf4j-api.jar
slf4j-log4j12.jar
This transport supports JMX. Download Quickfix/J from here: http://www.quickfixj.com/downloads. In the distribution
archive, you will find all the dependencies listed above. Also, refer to Quickfix/J documentation on configuring FIX
acceptors and initiators.
The FIX transport does not support any global parameters. All the FIX configuration parameters should be specified
at service level.

Service level FIX parameters

In transport parameter tables, literals displayed in italic mode under the "Possible Values" column should be
considered as fixed literal constant values. Those values can be directly put in transport configurations.

Parameter Name Description Required Possible Default Value


Values

transport.fix. URL to the Quickfix/J Required for A valid URL


AcceptorConfigURL acceptor configuration receiving
file (see notes below). messages over FIX

Copyright WSO2 Inc. 2005-2014 87


WSO2 Carbon 4.1.0

transport.fix. URL to the Quickfix/J Required for sending A valid URL


InitiatorConfigURL initiator configuration messages over FIX
file (see notes below).

transport.fix. Log f a c t o r y No console, file, jdbc L o g g i n g


AcceptorLogFactory implementation disabled
to be used for the
FIX acceptor (Determines
how logging is done at the

acceptor level).

transport.fix. Log f a c t o r y No console, file, jdbc L o g g i n g


InitiatorLogFactory implementation disabled
to be used for the
FIX acceptor (Determines
how logging is done at the

acceptor level).

transport.fix. Message store No memory, file, memory


AcceptorMessage mechanism to be sleepycat, jdbc
Store used with the
acceptor (Determines
how the FIX message
store is maintained).

transport.fix. Message store No memory, file, memory


InitiatorMessage mechanism to be sleepycat, jdbc
Store used with the initiator
(Determines how the
FIX message store is
maintained).

transport.fix. If the response FIX No


ResponseDeliverTo messages should
CompID be delivered to a
location different
from the location
the request was
originated, use this
property to set the
DeliverToCompID
field of the FIX
messages.

transport.fix. If the response FIX No


ResponseDeliverTo messages should
SubID be delivered to a
location different
from the location
the request was
originated, use this
property to set
the DeliverToSubID
field of the FIX
messages.

Copyright WSO2 Inc. 2005-2014 88


WSO2 Carbon 4.1.0

transport.fix. If the response FIX No


ResponseDeliverTo messages should
LocationID be delivered to a
location different
from the location
the request was
originated use this
property to set the
DeliverToLocationID
field of the FIX
messages.

transport.fix. By default, all received No true, false true


SendAllToInSequence FIX messages (including
responses) will be
directed to the in
sequence of the proxy
service.

Use this property to


override that behavior.

transport.fix. Whether the transport No true, false true


BeginStringValidation should validate
BeginString values
when forwarding FIX
messages across
sessions.

transport.fix. In situation where the No true, false false


DropExtraResponses FIX recipient sends
multiple responses
per request use this
parameter to drop
excessive responses
and use only the first
one.

Copyright WSO2 Inc. 2005-2014 89


WSO2 Carbon 4.1.0

Tools
The WSO2 Carbon platform has tools to analyze errors, various DEBUG logs such as wire logs, synase transport
logs etc. when troubleshooting the Carbon-based products. Some of them are discussed here:
Capturing the State of the System in Error Situations
Changing User Passwords in the Carbon Database
Encrypting and Decrypting Simple Texts
View and Resend Messages
WSO2 Carbon Secure Vault
Capturing the State of the System in Error Situations
Carbondump is a tool for collecting all the necessary data from a running Carbon instance at the time of an error.
The carbondump generates a zip archive with the collected data, which helps the WSO2 support team to analyze
your system and determine the problem which caused the error. Therefore, it is recommended that you run this tool
as soon as an error occurs in the Carbon instance.
When using the tool, you have to provide the process ID (pid) of the Carbon instance and the <PRODUCT_HOME>
which is where your unzipped Carbon distribution files reside. The command takes the following format:

sh carbondump.sh [-carbonHome path] [-pid of the carbon instance]

For example,

In Linux: sh carbondump.sh -carbonHome /home/user/wso2carbon-3.0.0/ -pid 5151

In Windows: carbondump.bat -carbonHome c:\wso2carbon-3.0.0\ -pid 5151

The tool captures the following information about the system:


Operating system information** OS (kernel) version
Installed modules lists and their information
List of running tasks in the system
Memory information of the Java process** Java heap memory dump
Histogram of the heap
Objects waiting for finalization
Java heap summary. GC algo used, etc.
Statistics on permgen space of Java heap
Information about the running Carbon instance** Product name and version
Carbon framework version (This includes the patched version)
<PRODUCT_HOME>, <JAVA_HOME>
configuration files
log files
H2 database files
Thread dump
Checksum values of all the files found in the $CARBON_HOME
Changing User Passwords in the Carbon Database
If an admin user forgets his password, he cannot retrieve it using the Management Console. In such a scenario, has
to change the password by running the chpasswd script located in <PRODUCT_HOME>/bin folder on the machine
that hosts the Carbon server.

Before executing this script, the Carbon instance should be shut down.

Copyright WSO2 Inc. 2005-2014 90


WSO2 Carbon 4.1.0

In order to change a user's password, you need to provide the following information:
The Carbon database URL: By default, WSO2 Carbon is shipped with H2 database so the default URL is: j
dbc:h2:repository/database/WSO2CARBON_DB;DB_CLOSE_ON_EXIT=FALSE. This URL may change
if a different database was specified during the installation. Then the URL will be in the form of jdbc:h2:/re
pository/database/WSO2CARBON_DB.
The Database driver class: For the default H2 database, the driver will be automatically picked up by the
system. If a different database is used, the driver class needs to be specified.
The database's username and password: Again for the default H2 database, the default username and
password will be used by the system. However, if a different username/password is used, you are required to
reset the admin password.
The username and new password of the user whose password is to be changed: If you do not provide
these as command line arguments, you will be prompted for it during execution.
The command line options available for chpasswd is as follows:

Command Line Option Description Mandatory?

--db-url The database URL Yes

--db-driver The database driver class No

--db-username The username for the database No

--db-password The password for the database No

--username The username of the user whose password is to be changed. No


If this is not given, you will be prompted for this field later.

--new-password The new password of the user whose password is to be changed. No

If this is not given, you will be prompted for this field later.

For example,

On Linux: chpasswd.sh --db-url "jdbc:h2:repository/database/WSO2CARBON_DB"

On Windows: chpasswd.bat --db-url "jdbc:h2:repsitory/database/WSO2CARBON_DB"

The following message is displayed if the password is updated successfully:

Password of user [username] updated successfully

If the database path includes directory names with spaces, the whole URL needs to be included within
quotations.

Encrypting and Decrypting Simple Texts


The cipher tool encrypts and decrypts simple texts. You can launch the tool by running the ciphertool.sh and
ciphertool.bat scripts available at <PRODUCT_HOME>/bin directory. The arguments accepted by this tool are as
follows:
keystore - If keys are in a store , its location

Copyright WSO2 Inc. 2005-2014 91


WSO2 Carbon 4.1.0

storepass - Password to access the keyStore


keypass - To get private key
alias - Alias to identify key owner
storetype - Type of the keystore. Default is JKS
keyfile - If key is in a file
opmode - Encrypt or decrypt. Default is encrypt
algorithm - Encrypt or decrypt algorithm. Default is RSA
source - Either cipher or plain text as an in-lined form
outencode - Currently base64 and used for encoding the result
inencode - Currently base64 and used to decode input
trusted - Is KeyStore a trusted store? If this argument is provided, consider as a trusted store
passphrase - if a simple symmetric encryption using a pass phrase shall be used
For example,

ciphertool.bat -source testpass -keystore resources/security/client-truststore.jks


-storepass wso2carbon -alias wo2carbon -outencode
base64 -trusted

View and Resend Messages


Users can view and monitor the messages passed along in a TCP-based conversation, using the TCPMon utility in
the WSO2 Carbon base platform. TCPMon is a simple and easy-to-use tool, particularly useful when developing
Web services. It is based on a swing UI and works on almost all platforms that support Java. You can find the script
file used to run this tool by the name tcpmon.sh or tcpmon.bat in the <PRODUCT_HOME>/bin folder. TCPMon
needs JRE 1.4 or higher to run and has no dependencies on third-party libraries.

Usage patterns of the tool

As an explicit intermediate

The most common usage of TCPMon is as an intermediary. It is called explicit since the client has to send the
messages to the intermediary rather than to the original endpoint in order to monitor the messages. The following
figure explains this concept.

In order to start TCPMon in this configuration, you have to provide the target host name and port as well as the
listening port on the Admin tab. For example,

Copyright WSO2 Inc. 2005-2014 92


WSO2 Carbon 4.1.0

Click 'Add' to open a new tab that displays the messages.

Copyright WSO2 Inc. 2005-2014 93


WSO2 Carbon 4.1.0

At this point, the requester should point to the listener port of the TCPMon instead of the original endpoint. For
example, assume that we need to monitor all the messages that are sent to and from www.apache.org.
Step 1:
Add a listener with the host 'www.apache.org' and port 80. Set the listener to port 8080, which is any unused port in
the local machine.

Step 2:
Point the browser to localhost:8080 instead of www.apache.org.

When the exchange of messages starts, it can be seen on the relevant tab.

Copyright WSO2 Inc. 2005-2014 94


WSO2 Carbon 4.1.0

The options at the bottom of the screen can be used to have the messages in XML format (useful in debugging Web
services), save and resend the messages and also to switch the layout of the message windows.

As a request sender for web services

TCPMon can also be used as a request sender for Web services. The request SOAP message can be pasted on
the send screen and sent directly to the server.

Copyright WSO2 Inc. 2005-2014 95


WSO2 Carbon 4.1.0

As a proxy

TCPMon can act as a proxy. To start it in proxy mode, select the Proxy option. When acting as a proxy, TCPMon
only needs the listener port to be configured.

Advanced settings

TCPMon can simulate a slow connection, in which case the delay and the bytes to be dropped can be configured.
This is useful when testing Web services.

Also, if HTTP proxy support is required, that can also be set on the admin screen.

Copyright WSO2 Inc. 2005-2014 96


WSO2 Carbon 4.1.0

WSO2 Carbon Secure Vault


WSO2 Carbon is shipped with a secure vault implementation which is a modified version of synapse secure vault.
This guide describes how to secure the plain text password in carbon configuration files.

Secret manager

The Secret Manager initializes the secret repository and the keystores. It uses secret repository to keep the secret
values (encrypted values). These secrets can be accessed through aliases. The keystore is required to create the
decryption crypto, which can be used to resolve encrypted secrets values. The keystore and secret repository are
configurable and the configuration can be done through the 'secret-conf.properties' file found in <PRODUCT_HOME>/
repository/conf/security directory.

Secret repository

This is used to store the secret values. Currently, there is only one secret repository implemented within secure vault
and it is called the FileBaseSecretRepository. It uses cipher-text.properties which can be found in <PRODUCT_HOME
>/repository/conf/security directory. It stores aliases vs. their actual secrets in encrypted format (encrypted
via a key in keystore). Any secret repositories can be written by implementing the SecretRepository and
SecretRepositoryProvider classes.

Secret callback

This provides the actual password for a given alias. There is a SecretManagerSecretCallbackHandler, which is
combined with secret manager to resolve the secret. Any callback can be written by implementing the
SecretCallbackHandler class.

Secret resolver

Any configuration builder, which uses secret information within its own configuration file, is needed to initialize the
secret resolver when building its own configuration. The secret resolver keeps a list of secured elements which need
to be defined in the configuration file with secret aliases. Secret resolver initializes the secret callback handler class,
which is defined in the configuration file.

Use secure vault with default configuration

In default configuration,
1. A file-base secret repository is used. The cipher-text.properties file can be found in <PRODUCT_HOME>/repo
sitory/conf/security directory.
2. Carbon Server's primary keystore is used for encrypting and decrypting passwords, which can be found in <P
RODUCT_HOME>/repository/resources/security folder.
3. DefaultSecretCallbackHandler (org.wso2.carbon.securevault.DefaultSecretCallbackHandler) is used as the
password resolver for the keystore and the private key passwords of the Carbon server's primary Keystore.
4. SecretManagerSecretCallbackHandler
(org.wso2.securevault.secret.handler.SecretManagerSecretCallbackHandler) is used as the password
resolver for all the secret values which are defined in the carbon configuration files.
The secure vault configuration is made easier by the command-line tool called Ciphertool.

Cipher tool

By default, the CipherTool can be used for creating encrypted values for given plaint text. There are two options for
secure vault configuration as follows:

Copyright WSO2 Inc. 2005-2014 97


WSO2 Carbon 4.1.0

- Dconfigure (sh ciphertool.sh -Dconfigure)

1. This option allows the user to secure plain text passwords in carbon configuration files.
2. Read alias values and their corresponding plain text passwords from the cipher-text.properties file. Note that
the CipherTool identifies plain text defined within square brackets as the plain text passwords. If a password
is not specified in the cipher-text.properties file for a corresponding alias, the user needs to provide it through
the command-line.
3. Check whether the alias is a known password alias in Carbon configurations. If the tool modifies the
configuration element and file, then replace the configuration element with the alias name. Define a secret
callback in the configuration file and add proper name spaces for defining the secure vault.
4. Encrypt the plain text value using the primary keystore of the carbon server (Details of the primary keytore is
taken from the carbon.xml file, which can be found in <PRODUCT_HOME>/repository/conf/security dir
ectory.)
5. Replace plain text values in the cipher-text.properties file with the encrypted passwords.
6. Add the default configuration to secret-conf.properties file

-Dchange (sh ciphertool.sh -Dchange)

1. This option allows the user to change a secured password.

The default secret CallbackHandler

This secret callback handler is used to resolve the keystore and private key passwords of the Carbon server's
primary keystore. As these passwords are needed to initialize the secret manager decrypted the encrypted values in
the secret repository, they act as the root passwords for the secure vault. Therefore, DefaultSecretCallbackHandler
provides two options for reading this password when starting the carbon sever.

Enter password in command-line

If option 2 is not configured, when the Carbon server is starting, it will propt to enter the private key and keystore
p a s s w o r d s .
The admin starting the server must provide the private key and keystore passwords using the command-line.
(Passwords are hidden from terminal and logs files.)
By default, the password provider assumes that both private key and keystore passwords are the same. If not, the
following system properties must be passed when the server is starting up.
export JAVA_OPTS=-Dkey.password=true (in UNIX)
This option is valid only when the Carbon server is started using sh wso2server.sh. When the server is started as a
daemon, this option can not be used.

Store the password in a temporary text file

When Carbon Server is starting, it first checks for the text file called "password" in <PRODUCT_HOME> and reads the
private key and keystore password. The text file is deleted automatically after it is read. The admin who starts the
Carbon Server must create a text file called "password" in <PRODUCT_HOME> and enter the keyStore password in
the first line of the file. Steps are as follows:
1. Shut down the server if it is already started.
2. Create a text file named "password" in <PRODUCT_HOME>.
3. Enter your primary keystore password in the 1st line of the text file and save it.
4. Start the Carbon Server using command, daemon. sh wso2server.sh -start
5. By default, the password provider assumes that both private key and keystore passwords are the same. If
not, the private key password must be entered in the second line of the file.

If the Carbon server is deployed in any other app server (e.g., weblogic) or key password of https
transport (password in mgt-transports.xml), it is not secured. Then the file name of the text file must
be 'password-tmp', not 'password'.

Copyright WSO2 Inc. 2005-2014 98


WSO2 Carbon 4.1.0

At every restart, the Admin has to create a text file.

Use secure vault with your own configurations

You can use your own configurations by changing the following according to your choice.
Secret repository.
Secret Callback Handler.
Using a keystore other than the primary keystore of the carbon server.
Let's see how we can write a new Secret Callback Handler class to secure the user management database
connection password. In this sample, you do not need to configure a secret repository or keyStore
(cipher-text.properties) as you are not going to store the secret or encrypted values.
Write a secret callback class. You need to implement the SecretCallbackHandler interface or extend the
AbstractSecretCallbackHandler abstract class. For example,

public class HardCodedSecretCallbackHandler extends AbstractSecretCallbackHandler {


protected void handleSingleSecretCallback(SingleSecretCallback
singleSecretCallback) {
singleSecretCallback.setSecret("password");
}
}

We can set multiple password-based as follows,

public class HardCodedSecretCallbackHandler extends AbstractSecretCallbackHandler {


protected void handleSingleSecretCallback(SingleSecretCallback
singleSecretCallback) {
if("foo".equals(singleSecretCallback.getId())){
singleSecretCallback.setSecret("foo_password");
} else if("bar".equals(singleSecretCallback.getId())){
singleSecretCallback.setSecret("bar_password");
}
}
}

Create a jar or an OSGI bundle. Copy the jar file to <PRODUCT_HOME>/repository/component/lib directory or the
OSGI bundle to <PRODUCT_HOME>/repository/component/dropins. Configure the user-mgt.xml file with an alias
name and your secret callback handler class name. For example,

Copyright WSO2 Inc. 2005-2014 99


WSO2 Carbon 4.1.0

<UserManagerxmlns:svns="http://org.wso2.securevault/configuration" >
<svns:SecureVault
provider="org.wso2.securevault.secret.handler.HardCodedSecretCallbackHandler">
<Realm>
<Configuration>
<AdminRole>admin</AdminRole>
<AdminUser>
<UserName>admin</UserName>
<Password>admin</Password>
</AdminUser>
<EveryOneRoleName>everyone</EveryOneRoleName>
<Property
name="url">jdbc:h2:repository/database/WSO2CARBON_DB;DB_CLOSE_ON_EXIT=FALSE</Property>
<Property name="userName">wso2carbon</Property>
<Property name="password"
svns:secretAlias="UserManager.Configuration.Property.password">password</Property>
<Property name="driverName">org.h2.Driver</Property>
<Property name="maxActive">50</Property>
<Property name="maxWait">60000</Property>
<Property name="minIdle">5</Property>
</Configuration>

Restart the server.

Secrets and alias list in Carbon configurations

Following are the alias names and secrets of carbon configuration files which are supported by secure vault.

transports.https.keystorePass -> SSL key and keystore password in mgt-transport.xml


Carbon.Security.KeyStore.Password- > Keystore password of Carbon server in carbon.xml
Carbon.Security.KeyStore.KeyPassword -> Private key password of Carbon server in
carbon.xml
Carbon.Security.TrustStore.Password -> Trust store password of Carbon server in
carbon.xml
UserManager.AdminUser.Password -> Admin User password in user-mgt.xml
UserManager.Configuration.Property.password -> User Manager database connection
password in user-mgt.xml
UserStoreManager.Property.ConnectionPassword -> User store connection password in
user-mgt .xml
wso2registry.[Registry Name].password -> Registry database connection password in
registry.xml
Axis2.Https.Listener.TrustStore.Password -> NIO Listener SSL trust store password in
axis2.xml
Axis2.Https.Listener.KeyStore.Password -> NIO Listener SSL keystore store password in
axis2.xml
Axis2.Https.Listener.KeyStore.KeyPassword -> NIO Listener SSL key password in
axis2.xml
Axis2.Https.Sender.TrustStore.Password -> NIO Sender SSL trust store password in
axis2.xml
Axis2.Https.Sender.KeyStore.Password -> NIO Sender SSL key store password in axis2.xml
Axis2.Https.Sender.KeyStore.KeyPassword -> NIO Sender SSL key password in axis2.xml
Axis2.Mailto.Parameter.Password -> Email sender password in axis2.xml

Copyright WSO2 Inc. 2005-2014 100


WSO2 Carbon 4.1.0

Developer Guide
This section describes the developer aspect of how to work with WSO2 Carbon. It contains the following topics:
Building from Source
Creating a Carbon Kernel Patch
Shipping a Kernel Patch with Distribution
Applying a Patch to the Kernel
Adding External Libraries
Building from Source
WSO2 invites you to contribute by checking out the source from the Subversion (SVN) source control system, buildi
ng the product and making changes, and then committing your changes back to the source repository. (For more
information on Subversion, see http://svnbook.red-bean.com/.) The following sections describe this process:
Checking out the source
Building the product
Setting up your development environment
Committing your changes

Building from source is optional. Users who do not want to make changes to the source code can simply do
wnload the binary distribution of WSO2 Carbon and install it.

Checking out the source

You can download the complete WSO2 Carbon platform, which is recommended if you intend to modify the source.
The Carbon project comes in three sub projects: Orbit, Kernel, and Platform. Download and build them in that
specific order. You can check out the source code anonymously using the checkout command as shown in the
following examples. Replace x.x.x with the version of Carbon you want to build and <local-x-directory> with
meaningful names, such as: svn checkout
https://svn.wso2.org/repos/wso2/carbon/orbit/tags/4.1.0 wso2carbon-orbit
Orbit:
$ svn checkout https://svn.wso2.org/repos/wso2/carbon/orbit/tags/x.x.x <local-orbit-d
irectory>

Kernel:
$ svn checkout https://svn.wso2.org/repos/wso2/carbon/kernel/tags/x.x.x <local-kernel
-directory>

Platform:
$ svn checkout https://svn.wso2.org/repos/wso2/carbon/platform/tags/x.x.x <local-plat
form-directory>

If you will not be committing changes, you can use HTTP instead of HTTPS to download the source
anonymously, which can be faster. If you are behind a corporate firewall, however, you might need to use
HTTPS if your access is blocked.

Access through a proxy

The Subversion client can be configured to access the repository through a proxy. Specify the proxy to use in the
"servers" configuration file in:
"~/.subversion" directory for Linux/Unix

Copyright WSO2 Inc. 2005-2014 101


WSO2 Carbon 4.1.0

"%APPDATA%\Subversion" hidden directory for Windows. (Try "echo %APPDATA%")


The comments in the file explain what to do. If you don't have this file, get the latest Subversion client and run any
command. It will create the configuration directory and template files.
For example, edit the 'servers' file and add something similar to the following:

[global]
http-proxy-host = your.proxy.name
http-proxy-port = 3128

Building the product

Following are the Apache Maven commands you can run to create complete release artifacts of WSO2 Carbon,
including the binary and source distributions.
Before you build:
1. Make sure the build server has an active Internet connection to download dependencies while building.
2. Install Maven and JDK. See Installation Prerequisites for compatible versions.
3. Set the environment variable MAVEN_OPTS="-Xms768m -Xmx3072m -XX:MaxPermSize=1200m" to
avoid the Maven OutOfMemoryError.

Command Description

mvn clean install The binary and source distributions

mvn clean install -Dmaven.test.skip=true The binary and source distributions, without running
any of the unit tests.

mvn clean install -Dmaven.test.skip=true -o The binary and source distributions, without running
any of the unit tests, in offline mode. This can be
done only if you have already built the source at
least once.

Setting up your development environment

Before you edit the source code in your IDE, set up your development environment by running one of the following
commands:

IDE Command Additional information

Eclipse mvn eclipse:eclipse http://maven.apache.org/plugins/maven-eclipse-plugin/

IntelliJ IDEA mvn idea:idea http://maven.apache.org/plugins/maven-idea-plugin/

Committing your changes

If you are a committer, you can commit your changes using the following command (SVN will prompt you for your
password):
$ svn commit --username your-username -m "A message"

Creating a Carbon Kernel Patch

Copyright WSO2 Inc. 2005-2014 102


WSO2 Carbon 4.1.0

When creating a patch release of a product based on Carbon 4.1.0 and later, you use the public patching model to
create the Carbon kernel patch as described below.
The following is the kernel branch svn/git structure.

Example:

After each kernel release, the patches directory is the only directory that allows commit access.

To create a Carbon kernel patch:

1. Create a JIRA issue to explain extensively about the fix in the patch.
One patch has many fixes; therefore, explain each fix in a separate JIRA issue in the public JIRA ( http://wso2
.org/jira ), Carbon project. Thereafter, add the links of the created JIRA issues to the README file.
2. Create the relevant patch folder (patch000x) under the patches directory.
3. Use the SVN copy function to copy the relevant components that have to be fixed to the patch folder.

Keep in mind the following:


When creating fixes, API changes are not allowed
This patching process is only allowed in the repository/component/plugins directory

4. Add the following .txt files to the patch directory:

File Name Description

README This file includes the following details:


1. Patch ID (e.g., WSO2-CARBON-PATCH-4.1.0-0001)
2. Applies To (e.g., WSO2 CARBON 4.1.0)
3. Associated public JIRAs
4. Details about the fix

LICENSE Details about Apache License 2.0 ( http://www.apache.org/licenses/LICENSE-2.


0.html)

wso2carbon-version Details about the Carbon server version (e.g., WSO2 Carbon Framework v4.1.0
patch0001)

The patch directory structure should now look like this:

Copyright WSO2 Inc. 2005-2014 103


WSO2 Carbon 4.1.0

5. If you are patching a component at the dependency level, create a dependencies directory only if it is not al
ready created under the respective patch folder.

6. Use the SVN copy function to copy the relevant dependency component that needs to be patched to the pat
ch directory.

7. If the dependency includes an orbit pom, create an orbit directory only if it is not already created under the
respective patch directory.

8. Use the SVN copy function to copy the relevant orbit POM component which needs to be patched to the pat
c h d i r e c t o r y .

Example: If you want to patch the axis2 kernel along with some other Carbon component (i.e.,org.wso2
.carbon.xxxx), the file structure should be as follows:

Copyright WSO2 Inc. 2005-2014 104


WSO2 Carbon 4.1.0

9. Create the Assembly file (bin.xml), if it has not already been created.

The Assembly file (bin.xml) that is found in the distribution directory is responsible for aggregating and
creating the patch file (e.g., to copy the LICENSE, README, wso2carbon-version.txt files). It is
responsible for copying the relevant patched JARs from the target directories to the composite patch
d i r e c t o r y .

E x a m p l e :
Please see http://maven.apache.org/plugins/maven-assembly-plugin/ for an overview on assembly files (bin
.xml).

For function definitions see http://maven.apache.org/plugins/maven-assembly-plugin/assembly.html.

Copyright WSO2 Inc. 2005-2014 105


WSO2 Carbon 4.1.0

<assembly>
<includeBaseDirectory>true</includeBaseDirectory>
<baseDirectory></baseDirectory>
<id>carbon-patch-0001</id>
<formats>
<format>zip</format>
</formats>
<files>
<file>

<source>../org.wso2.carbon.core/target/org.wso2.carbon.core-4.1.0.jar</source>

<outputDirectory>WSO2-CARBON-PATCH-4.1.0-0001/patch0001</outputDirectory>
<destName>org.wso2.carbon.core_4.1.0.jar</destName>
<fileMode>644</fileMode>
</file>
<file>
<source>../wso2carbon-version.txt</source>
<outputDirectory>WSO2-CARBON-PATCH-4.1.0-0001</outputDirectory>
<fileMode>644</fileMode>
<filtered>true</filtered>
</file>
<file>
<source>../README.txt</source>
<outputDirectory>WSO2-CARBON-PATCH-4.1.0-0001</outputDirectory>
<fileMode>644</fileMode>
<filtered>true</filtered>
</file>
<file>
<source>../LICENCE.txt</source>
<outputDirectory>WSO2-CARBON-PATCH-4.1.0-0001</outputDirectory>
<fileMode>644</fileMode>
<filtered>true</filtered>
</file>
</files>
</assembly>

10. Create the root POM file , if it has not already been created.
The root POM file is what builds the whole structure and calls the assembly plug-in. When building this, it will
first build the components and then call the assembly plug-in to create the patch ZIP file under the distribution
directory.
Example:
Please see http://maven.apache.org/plugins/maven-assembly-plugin/ for more information.

Copyright WSO2 Inc. 2005-2014 106


WSO2 Carbon 4.1.0

<project xmlns="http://maven.apache.org/POM/4.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0
http://maven.apache.org/maven-v4_0_0.xsd">

<parent>
<groupId>org.wso2.carbon</groupId>
<artifactId>carbon-parent</artifactId>
<version>4.1.0</version>
<relativePath>../../parent/pom.xml</relativePath>
</parent>

<modelVersion>4.0.0</modelVersion>
<artifactId>WSO2-CARBON-PATCH-4.1.0</artifactId>
<version>0001</version>
<packaging>pom</packaging>
<name>Distribution-Aggregate</name>
<description>WSO2 Carbon Patch 0001 - Distribution</description>
<url>http://wso2.org</url>

<modules>
<module>org.wso2.carbon.core</module>
</modules>

<build>
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-assembly-plugin</artifactId>
<version>2.4</version>
<executions>
<execution>
<id>2-dist</id>
<phase>package</phase>
<goals>
<goal>attached</goal>
</goals>
<configuration>
<outputDirectory>distribution</outputDirectory>
<descriptors>
<descriptor>${basedir}/bin.xml</descriptor>
</descriptors>
<appendAssemblyId>false</appendAssemblyId>
</configuration>
</execution>
</executions>
</plugin>
</plugins>
</build>
</project>

These patches will go into the already running production environments as service packs. Patch 0001 to
Patch 0100 is the numbering format reserved for kernel patches .

Copyright WSO2 Inc. 2005-2014 107


WSO2 Carbon 4.1.0

Shipping a Kernel Patch with Distribution


After a kernel public patch is released, the respective product team should follow the following steps to add the
patches to the product distribution, if a product that is based on Carbon 4.1.0 kernel needs to ship the patch by
default.

To ship a kernel patch with a product distribution:

1. Add the patch to the respective product distribution build. Follow the identical process that you use to add a
Carbon kernel distribution (wso2carbon-core-<version>.zip) to a product distribution using the maven
d e p e n d e n c y p l u g - i n .

Example:
For more information on the Maven dependency plugin, please see http://maven.apache.org/plugins/maven-d
ependency-plugin/

<!-- Unzipping WSO2-CARBON-PATCH-4.1.0-0001-->


<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-dependency-plugin</artifactId>
<version>2.0-alpha-4</version>
<inherited>false</inherited>
<execution>
<id>unpack-kernel-patch</id>
<phase>test</phase>
<goals>
<goal>unpack</goal>
</goals>
<configuration>
<artifactItems>
<artifactItem>
<groupId>org.wso2.carbon</groupId>

<artifactId>WSO2-CARBON-PATCH-4.1.0</artifactId>
<version>0001</version>
<type>zip</type>
<overWrite>true</overWrite>
<outputDirectory>target</outputDirectory>
</artifactItem>
</artifactItems>
</configuration>
</execution>
<plugin>
<plugins>

2. Make sure that when the distribution gets built for a product, the libraries/jars in the patch directory
(e.g., patch0xxx) gets copied to the

{CARBON_HOME}/repository/components/patches/patch0xxx directory.

Example:

Copyright WSO2 Inc. 2005-2014 108


WSO2 Carbon 4.1.0

<!-- Copying WSO2-CARBON-PATCH-4.1.0-0001 files to the patches directory-->


<fileSet>

<directory>../p2-profile-gen/target/WSO2-CARBON-PATCH-4.1.0-0001</directory>

<outputDirectory>wso2as-${pom.version}/repository/components/patches/</outputDire
ctory>
<includes>
<include>**/patch0001/*.*</include>
</includes>
</fileSet>

Applying a Patch to the Kernel


Users apply various patches to the existing Carbon-based products to enhance the available features or to fix possib
le bugs that may rise on the Carbon-based application. As a result, applying patches is an easy approach to use
when existing executable JAR files need to be changed on the server.
To apply a patch:
1. Insert the required patches to the respective <PRODUCT_HOME>/repository/components/patches dire
c t o r y .
For example: <PRODUCT_HOME>/repository/components/patches
2. Run the patch as follows:
wso2server.sh -DapplyPatches

When running this patch the following is the sequence of actions that take place:
A backup folder named patch0000 gets created inside the <PRODUCT_HOME>/repository/compon
ents/patches directory containing the original content of the <PRODUCT_HOME>/repository/com
ponents/plugins folder. This step is executed as a precautionary measure so that if something
goes wrong it is possible to revert to the previous state.
The content of the patches directory will incrementally (e.g., patch0001, patch0002 etc.) get copied to
the plugins directory.
This process is only supported for components that have already existing JAR files in the plugins dir
ectory.

Adding External Libraries


Users need to apply different external JAR files to the existing Carbon server to enhance or introduce new features t
o the Carbon application. OSGi bundles are used to implement WSO2 Carbon. As a result, if needed to extend a
platform the OSGi bundles need to be dropped into the Carbon server.

To add external libraries:

The users are allowed to apply JARs to various directories as required. The WSO2 Carbon OSGi repository is
available in the $CARBON_HOME/repository/components directory. When extracting a Carbon or Carbon-based
product, $CARBON_HOME is the folder that gets generated. The user has to manually insert all the corresponding
entries in these components to the bundles.info file at the following location:

$CARBON_HOME/repository/components/configuration/org.eclipse.equinox.simpleconfigurat
or/bundles.info

Use the following directories to drop external libraries to the Carbon Server:

Copyright WSO2 Inc. 2005-2014 109


WSO2 Carbon 4.1.0

Directory Description

$CARBON_HOME/repository/components/dropins OSGi bundles which needs to be applied .

$CARBON_HOME/repository/components/lib Dropped JAR files that will be converted to OSGi


bundles at startup and copied to the dropins
d i r e c t o r y .

$CARBON_HOME/repository/components/extensions Dropped JAR files that will be converted to OSGi


Framework Extension bundles at startup and
copied to the dropins directory .

After adding all the required libraries, restart the server to apply the changes.

Copyright WSO2 Inc. 2005-2014 110


WSO2 Carbon 4.1.0

Reference Guide
The following topics provide reference information for working with WSO2 Carbon:
Default Ports of WSO2 Products
Default Ports of WSO2 Products
This page describes the default ports that are used for each WSO2 product when the port offset is 0.
Common ports
Product-specific ports

Common ports

The following ports are common to all WSO2 products that provide the given feature. Some features are bundled in
the WSO2 Carbon platform itself and therefore are available in all WSO2 products by default.

Management console ports

WSO2 products that provide a management console use the following servlet transport ports:
9443 - HTTPS servlet transport (the default URL of the management console is https://localhost:9443/carbon)
9763 - HTTP servlet transport

LDAP server ports

Provided by default in the WSO2 Carbon platform.


10389 - Used in WSO2 products that provide an embedded LDAP server

KDC ports

8000 - Used to expose the Kerberos key distribution center server

JMX monitoring ports

WSO2 Carbon platform uses TCP ports to monitor a running Carbon instance using a JMX client such as JConsole.
By default, JMX is enabled in all products. You can disable it using <PRODUCT_HOME>/repository/conf/etc/j
mx.xml file.

11111 - RMIRegistry port. Used to monitor Carbon remotely


9999 - RMIServer port. Used along with the RMIRegistry port when Carbon is monitored from a JMX client
that is behind a firewall

Clustering ports

To cluster any running Carbon instance, either one of the following ports must be opened.
45564 - Opened if the membership scheme is multicast
4000 - Opened if the membership scheme is wka

Random ports

Certain ports are randomly opened during server startup. This is due to specific properties and configurations that
become effective when the product is started. Note that the IDs of these random ports will change every time the
server is started.
A random TCP port will open at server startup because of the -Dcom.sun.management.jmxremote prope
rty set in the server startup script. This property is used for the JMX monitoring facility in JVM.
A random UDP port is opened at server startup due to the log4j appender ( SyslogAppender), which is

Copyright WSO2 Inc. 2005-2014 111


WSO2 Carbon 4.1.0

configured in the <PRODUCT_HOME>/repository/conf/log4j.properties file.

Product-specific ports

Some products open additional ports.


API Manager | BAM | BPS | Data Analytics Server | Complex Event Processor | Elastic Load Balancer | ESB | Identi
ty Server | Message Broker | Machine Learner | Storage Server | Enterprise Mobility Manager

API Manager

10397 - Thrift client and server ports


8280, 8243 - NIO/PT transport ports
7711 - Thrift SSL port for secure transport, where the client is authenticated to BAM/CEP: stat pub

If you change the default API Manager ports with a port offset, most of its ports will be changed
automatically according to the offset except a few exceptions described in the APIM Manager
documentation.

BAM

9160 - Cassandra port using which Thrift listens to clients


7711 - Thrift SSL port for secure transport, where the client is authenticated to BAM
7611 - Thrift TCP port to receive events from clients to BAM
21000 - Hive Thrift server starts on this port

BPS

2199 - RMI registry port (datasources provider port)

Data Analytics Server

9160 - Cassandra port on which Thrift listens to clients


7711 - Thrift SSL port for secure transport, where the client is authenticated to DAS
7611 - Thrift TCP port to receive events from clients to DAS
For a list of Apache Spark related ports, see WSO2 Data Analytics Server Documentation - Spark
Configurationss.

Complex Event Processor

9160 - Cassandra port on which Thrift listens to clients


7711 - Thrift SSL port for secure transport, where the client is authenticated to CEP
7611 - Thrift TCP port to receive events from clients to CEP
11224 - Thrift TCP port for HA management of CEP

Elastic Load Balancer

8280, 8243 - NIO/PT transport ports

ESB

Non-blocking HTTP/S transport ports: Used to accept message mediation requests. If you want to send a request to
an API or a proxy service for example, you must use these ports. ESB_HOME}/repository/conf/axis2/axis2.xml file.

8243 - Passthrough or NIO HTTPS transport


8280 - Passthrough or NIO HTTP transport

Identity Server

Copyright WSO2 Inc. 2005-2014 112


WSO2 Carbon 4.1.0

8000 - KDCServerPort. Port which KDC (Kerberos Key Distribution Center) server runs
10500 - ThriftEntitlementReceivePort

Message Broker

Message Broker uses the following JMS ports to communicate with external clients over the JMS transport.
5672 - Port for listening for messages on TCP when the AMQP transport is used.
8672 - Port for listening for messages on TCP/SSL when the AMQP Transport is used.
1883 - Port for listening for messages on TCP when the MQTT transport is used.
8833 - Port for listening for messages on TCP/SSL when the MQTT Transport is used.
7611 - The port for Apache Thrift Server.

Machine Learner

7077 - The default port for Apache Spark.


54321 - The default port for H2O.
4040 - The default port for Spark UI.

Storage Server

Cassandra:
7000 - For Inter node communication within cluster nodes
7001 - For inter node communication within cluster nodes vis SSL
9160 - For Thrift client connections
7199 - For JMX
HDFS:
54310 - Port used to connect to the default file system.
54311 - Port used by the MapRed job tracker
50470 - Name node secure HTTP server port
50475 - Data node secure HTTP server port
50010 - Data node server port for data transferring
50075 - Data node HTTP server port
50020 - Data node IPC server port

Enterprise Mobility Manager

The following ports need to be opened for Android and iOS devices so that it can connect to Google Cloud
Messaging (GCM)/Firebase Cloud Messaging (FCM) and APNS (Apple Push Notification Service) and enroll to
WSO2 EMM.
A n d r o i d :
The ports to open are 5228, 5229 and 5230. GCM/FCM typically only uses 5228, but it sometimes uses 5229 and
5 2 3 0 .
GCM/FCM does not provide specific IPs, so it is recommended to allow the firewall to accept outgoing connections
to all IP addresses contained in the IP blocks listed in Google's ASN of 15169.
iOS:
5223 - TCP port used by devices to communicate to APNs servers
2195 - TCP port used to send notifications to APNs
2196 - TCP port used by the APNs feedback service
443 - TCP port used as a fallback on Wi-Fi, only when devices are unable to communicate to APNs on port
5223
The APNs servers use load balancing. The devices will not always connect to the same public IP address for
notifications. The entire 17.0.0.0/8 address block is assigned to Apple, so it is best to allow this range in the
firewall settings.

Copyright WSO2 Inc. 2005-2014 113


WSO2 Carbon 4.1.0

API Manager:

The following WSO2 API Manager ports are only applicable to WSO2 EMM 1.1.0 onwards.

10397 - Thrift client and server ports


8280, 8243 - NIO/PT transport ports

Copyright WSO2 Inc. 2005-2014 114


WSO2 Carbon 4.1.0

Getting Support
In addition to this documentation, there are several ways to get help as you work on WSO2 products.

Explore learning resources: For tutorials, articles, whitepapers, webinars, and other learning
resources, look in the Resources menu on the WSO2 website. For training materials, click WSO2
Training on the Support & Training menu. In products that have a visual user interface, click the
Help link in the top right-hand corner to get help with your current task.

Try our support options: WSO2 offers a variety of development and production support
programs, ranging from web-based support during normal business hours to premium 24x7 phone
support. For support information, see http://wso2.com/support/.

Ask questions in the user forums at http://stackoverflow.com. Ensure that you tag your question
with appropriate keywords such as WSO2 and the product name so that our team can easily find
your questions and provide answers. If you can't find an answer on the user forum, you can email
the WSO2 development team directly using the relevant mailing lists described at http://wso2.org/
mail.

Report issues, submit enhancement requests, track and comment on issues using our public
bug-tracking system, and contribute samples, patches, and tips & tricks (see the WSO2
Contributor License Agreement).

Copyright WSO2 Inc. 2005-2014 115


WSO2 Carbon 4.1.0

Site Map
Use this site map to quickly find the topic you're looking for by searching for a title on this page using your browser's
search feature. You can also use the search box in the upper right corner of this window to search for a word or
phrase in all the pages in this documentation.

Copyright WSO2 Inc. 2005-2014 116

You might also like