Professional Documents
Culture Documents
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
mvn eclipse:eclipse
mvn idea:idea
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.
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.
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.
Carbon Features
Feature Description
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.
Governance Registry Govern and monitor large-scale deployments, including clustered servers and cloud
Integration implementations.
Applied across the entire WSO2 Carbon middleware platform.
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.
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.
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.
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.
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
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 .
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 .
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.
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
Follow the instructions below to install the required applications and the WSO2 product on Linux.
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.
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 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}
If you do not know how to work with text editors in a Linux SSH session, run the following command:
4. To verify that the JAVA_HOME variable is set correctly, execute the following command:
echo $JAVA_HOME
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.
Follow the instructions below to install the required applications and the product on Solaris.
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.
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}
If you do not know how to work with text editors in an SSH session, run the following command:
4. To verify that the JAVA_HOME variable is set correctly, execute the following command: echo $JAVA_HOME
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.
Installation PrerequisitesBe sure your system meets the , Java Development Kit (JDK) is essential to run 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. 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.
3. Click the Newbutton under "System variables" (for all users) or under "User variables" (just for the user who is
currently logged in).
set JAVA_HOME
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
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.
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.
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.
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 =
-Dorg.apache.jasper.runtime.BodyContentImpl.LIMIT_BUFFER=true
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.
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:
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.
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.
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.
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.
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.
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"
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
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:
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:
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.
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.
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.
OS Command
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".
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:
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
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>
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.
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,
https://<Server Host>:9443/carbon.
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:
Menu items
Anonymous users can access some menu items including the "Home" menu displayed on the left-hand-side panel.
Links to resources
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,
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>
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.
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
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 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.
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
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}$
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,
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.
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.
3. From the list of users, select the one you want to delete and click the "Delete" link associated with it.
Follow the instructions below to change the password of the user currently logged in.
For example,
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.
4. A notification is displayed that the current user's password has been changed. Click "OK".
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.
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
2. In the "User Management" window which appears, click the "Roles" 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.
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".
5. The user role will be changed. The program goes back to the user menu.
3. Click the "Delete" link associated with the role you want to delete.
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 properties of the user Realm Configuration can be explained as follows. It mainly contains details for the
database connection.
MultiTenantRealmConfigBuilder Tenant Manager specific realm config parameter. Can be used to build
different types of realms for the tenant.
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.
For Linux:
sh wso2server.sh
For Windows:
wso2server.bat
sh wso2server.sh -Dsetup
For Windows:
wso2server.bat -Dsetup
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.
<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">^[^~!#$;%^*+={}\\|\\\\<>,\'\"]{3,30}$</Property>
<Property name="UsernameJavaScriptRegEx">[\\S]{3,30}</Property>
<Property
name="RolenameJavaRegEx">^[^~!@#$;%^*+={}\\|\\\\<>,\'\"]{3,30}$</Property>
<Property name="RolenameJavaScriptRegEx">[\\S]{3,30}</Property>
<Property name="UserRolesCacheEnabled">true</Property>
</UserStoreManager>
ReadOnly Indicates whether the user store of this realm operates in the user read only
mode or not.
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.
PasswordJavaScriptRegEx The regular expression used by the font-end components for password
validation.
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.
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.
<Property
name="MultiTenantRealmConfigBuilder">org.wso2.carbon.user.core.config.multitenanc
y.SimpleRealmConfigBuilder</Property>
<UserStoreManager class="org.wso2.carbon.user.core.jdbc.JDBCUserStoreManager">
...
<Property name="passwordHashMethod">SHA</Property>
...
</UserStoreManager>
<TenantManager
class="org.wso2.carbon.user.core.tenant.JDBCTenantManager"></TenantManager>
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.
<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">(&(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">^[^~!@#$;%^*+={}\\|\\\\<>,\'\"]{3,30}$</Property>
<Property name="RolenameJavaScriptRegEx">[\\S]{3,30}</Property>
<Property
name="RolenameJavaRegEx">^[^~!@#$;%^*+={}\\|\\\\<>,\'\"]{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">(&(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-->
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.
UserNameListFilter Filtering criteria for listing all the user entries in LDAP.
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.
UserNameAttribute Attribute used for uniquely identifying a user entry. Users can be authenticated
using their email address, uid and etc .....
UsernameJavaScriptRegEx The regular expression used by the font-end components for username
validation.
RolenameJavaScriptRegEx The regular expression used by the font-end components for rolename
validation.
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.
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.
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.
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.
<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>
<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>
</Realm>
</UserManager>
<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>
<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>
<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.
<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>
MaxUserNameListLength
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.
GroupNameListFilter Filtering criteria for listing all the group entries in LDAP.
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:
<UserStoreManager
class="org.wso2.carbon.user.core.ldap.ReadWriteLDAPUserStoreManager">
<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">(&(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">^[^~!@#$;%^*+={}\\|\\\\<>,\'\"]{3,30}$</Property>
<Property name="RolenameJavaScriptRegEx">[\\S]{3,30}</Property>
<Property
name="RolenameJavaRegEx">^[^~!@#$;%^*+={}\\|\\\\<>,\'\"]{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">(&(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>
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.
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.
UserNameAttribute Attribute used for uniquely identifying a user entry. Users can be authenticated
using their email address, uid etc.
UsernameJavaScriptRegEx The regular expression used by the font-end components for username validation.
RolenameJavaScriptRegEx The regular expression used by the font-end components for rolename validation.
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.
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.
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:
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>
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.
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 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,
2. The Repository Management tab allows you to view or modify feature management settings.
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.
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,
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.
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.
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,
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.
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.
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.
6. The Install Details window appears.Verify the provided information and click Next.
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.
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.
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,
Installed Features
1. Log on to the product's Management Console and select Features from the Configure menu.
For example,
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.
For example,
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,
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
Note
Screenshots in this section are taken using the WSO2 Carbon product. They may vary depending on the
product you are installing.
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 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
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
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.
2. The Server Roles page appears. Chose the role you want to delete and click the Delete link associated with it.
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
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
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.
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
org.wso2.carbon.server.transports.http.HttpTransport
This servlet transport implementation can be further tuned up using the following parameters.
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.
compression Use this parameter to enable content No on, off, force off
compression and save server
bandwidth.
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.
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
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.
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.
keystore Path to the keystore which should be used for Yes A valid file path to a
encryption/decryption. keystore file
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.
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.
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.
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.
port The port on which this transport No A positive integer less than 8280
receiver should listen for incoming 65535
messages.
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.
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 '|'
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.
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.
</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.
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.
By default the
response file will
be completely
overwritten.
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.
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.
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.
transport.jms.IdleTaskLimit The number of idle runs per thread before it dies No Any positive in
out.
JMS transport implementation has some parameters that should be configured at service level, in other words in
service XML files of individual services.
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.
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.
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.
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.
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
The TCP transport sender does not accept any configuration parameters as of now.
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.
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/</ServerURL>
<transportSender name="local"
class="org.apache.axis2.transport.local.LocalTransportSender"/>
<transportReceiver name="local"
class="org.wso2.carbon.core.transports.local.CarbonLocalTransportReceiver"/>
<transportSender name="local"
class="org.wso2.carbon.core.transports.local.CarbonLocalTransportSender"/>
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.
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.
acceptor level).
acceptor level).
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:
For example,
Before executing this script, the Carbon instance should be shut down.
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:
If this is not given, you will be prompted for this field later.
For example,
If the database path includes directory names with spaces, the whole URL needs to be included within
quotations.
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,
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.
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.
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.
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.
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.
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:
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
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.
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.
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'.
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,
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,
<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>
Following are the alias names and secrets of carbon configuration files which are supported by secure vault.
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.
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.
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
[global]
http-proxy-host = your.proxy.name
http-proxy-port = 3128
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 -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.
Before you edit the source code in your IDE, set up your development environment by running one of the following
commands:
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"
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.
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.
wso2carbon-version Details about the Carbon server version (e.g., WSO2 Carbon Framework v4.1.0
patch0001)
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:
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).
<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.
<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 .
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/
<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:
<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>
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.
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:
Directory Description
After adding all the required libraries, restart the server to apply the changes.
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.
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
KDC 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.
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
Product-specific ports
API Manager
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
BPS
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.
Identity Server
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
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
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.
API Manager:
The following WSO2 API Manager ports are only applicable to WSO2 EMM 1.1.0 onwards.
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).
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.