WSO2 Carbon - System Administration Guide [ Documentation Index ]

WSO2 Carbon System Administration Guide

This guide provides useful information to administrate a WSO2 Carbon instance. It contains information on how to configure and maintain various aspects of WSO2 Carbon. This guide also explains the directory structure, various configuration files and how to configure the system using these configuration files.

Contents

Downloading WSO2 Carbon

Binary distributions and source distributions of WSO2 Carbon can be downloaded from the WSO2 Carbon home page in the WSO2 Oxygen Tank. Before proceeding to the downloads page you will be asked to register on the WSO2 Oxygen Tank. Registration is free and optional however it is recommended that you sign up for an account right away since registered Oxygen Tank users get exclusive access to our support forums and tons of valuable content related to SOA and Web Services. Once you are on the downloads page click on the relevant links to download a binary distribution or a source distribution of the latest stable release of the WSO2 Carbon. If you are interested in an older version of the Carbon, scroll down in the downloads page to locate the links to previous releases. You will also find links to download developer releases and nightly builds of the WSO2 Carbon on the same page. We recommend that you always download the latest stable release. If you want to try out a feature that was added very recently you can try out a nightly build. If you downloaded a source distribution of the Carbon you need to build the source to get the executable binary. WSO2 Carbon uses an Apache Maven2 based build system and therefore you need to first download and install Apache Maven2. Please refer Maven2 documentation on installing and configuring Apache Maven2. Also note that Apache Maven2 requires Java to run. Once Maven2 is properly configured extract the downloaded source distribution and change your working directory to the directory that is created. Then execute the command 'mvn clean install' to run the builder. Once the build process is complete you can find the binary distribution archive in CARBON_SRC_HOME/modules/distribution/target directory.('CARBON_SRC_HOME' refers to the directory in the file system where WSO2 Carbon source distribution is installed)

Downloading WSO2 Carbon

Once you extract the binary distribution of WSO2 Carbon, you will be able to see the following directory layout.
Directory Description
bin Contains all the necessary scripts to interact with the WSO2 Carbon instance. There are shell scripts (with .sh extension) for Unix/Linux users and batch files (with .bat extension) for Windows users. In general you will find the following scripts in this directory.
  • wso2server.sh/wso2server.bat - Launches WSO2 Carbon
  • wsdl2java.sh/wsdl2java.bat - Launches the Java stub generation tool for Web Services
  • java2wsdl.sh/java2wsdl.bat - Launches the WSDL generation tool for Java Web Services
  • tcpmon.sh/tcpmon.bat - Launches TCPMon, the TCP connection monitor
  • chpasswd.sh/chpasswd.bat -Use this script to change the administrator password without signing in to the server

  • daemon.sh -Start WSO2 Carbon as a daemon on Unix/Linux systems

  • install.bat - Install WSO2 Carbon as a background service on Windows

  • repowriter.sh/repowriter.bat
dbscripts Contains a collection of database scripts required to create the Carbon database on a variety of database management systems.
lib The lib directory houses all the jar files and OSGi bundles required by the embedded Tomcat instance. The log4j.properties file used by the Carbon is also stored here.
repository repository is the main repository for all kind of deployments and configurations in Carbon. This includes all Axis2 artifacts, Synapse artifacts etc. In addition to that, Axis2 configurations, Carbon configurations etc are also hosted under this folder.
  • lib - Directory contains all the client side Axis2 libraries. These libraries will be copied here after starting the server once or by running 'ant' from CARBON_HOME/bin.
  • deployment - Directory can be used to deploy Axis2 (can have Synapse, BPel stuff as well) artifacts for both server side and client side. See deployment/README for more details.
  • conf - Directory contains all the configuration files. axis2.xml, carbon.xml etc.
  • components - Directory contains all OSGi related stuff. Carbon bundles, OSGi configuration files and p2 stuff.
    • plugins - This contains all OSGi bundles that are used to run the server.
    • p2 - Contains Carbon provisioning (p2) related configuration files.
    • lib - If you want any third part libraries to be used as OSGi bundles in the system, copy those libraries into this directory.
    • dropins - If you have OSGi bundles that should be added to Carbon, copy those into this directory.
    • configuration - OSGi specific configuration files.

  • logs - Directory contains all Carbon logs.

  • tenants - Directory will contain relevant tenant artifacts in the case of a multitenant deployment.

resources Contains additional resources required by WSO2 Carbon. This includes security related resources such as keystores.
tmp The temporary files directory used by the Carbon

Installing and Running WSO2 Carbon

Extract the downloaded binary distribution into your file system. If you built WSO2 Carbon from source extract the archive created by the builder. In order to be able to start WSO2 Carbon you need Java 6. Set JAVA_HOME variable pointing to the directory in which Java is installed.

Installing and Running WSO2 Carbon

Go to CARBON_HOME/bin directory and if you are on Unix/Linux execute the wso2server.sh shell script or if you are on Windows execute the wso2server.bat batch file. This will start the Carbon and you can see the progress of the startup procedure on the console. Please note that server startup may take some time depending on the hardware configuration of your system. If the server started up cleanly you should get an output similar to the following on the console.
  [2010-11-30 17:15:26,251]  INFO {org.wso2.carbon.server.Main} -  Initializing system...
[2010-11-30 17:15:26,511]  INFO {org.wso2.carbon.server.TomcatCarbonWebappDeployer} -  Deployed Carbon webapp: StandardEngine[carbonEngine].StandardHost
    [defaulthost].StandardContext[/]
OSGi console has been enabled with options: -console

osgi> [2010-11-30 17:15:31,436]  INFO {org.wso2.carbon.core.internal.CarbonCoreActivator} -  Starting WSO2 Carbon...
[2010-11-30 17:15:31,453]  INFO {org.wso2.carbon.core.internal.CarbonCoreActivator} -  Operating System : Linux 2.6.28-11-generic, amd64
[2010-11-30 17:15:31,453]  INFO {org.wso2.carbon.core.internal.CarbonCoreActivator} -  Java Home        : /opt/softwares/jdk1.6.0_13/jre
[2010-11-30 17:15:31,453]  INFO {org.wso2.carbon.core.internal.CarbonCoreActivator} -  Java Version     : 1.6.0_13
[2010-11-30 17:15:31,453]  INFO {org.wso2.carbon.core.internal.CarbonCoreActivator} -  Java VM          : Java HotSpot(TM) 64-Bit Server VM 11.3-b02,Sun Microsystems Inc.
[2010-11-30 17:15:31,454]  INFO {org.wso2.carbon.core.internal.CarbonCoreActivator} -  Carbon Home      : /home/user/wso2carbon-3.1.0
[2010-11-30 17:15:31,454]  INFO {org.wso2.carbon.core.internal.CarbonCoreActivator} -  Java Temp Dir    : /home/user/wso2carbon-3.1.0
[2010-11-30 17:15:31,454]  INFO {org.wso2.carbon.core.internal.CarbonCoreActivator} -  User             : user, en-US, Asia/Colombo
[2010-11-30 17:15:34,266]  INFO {org.wso2.carbon.registry.core.internal.RegistryCoreServiceComponent} -  Registry Mode    : READ-WRITE
[2010-11-30 17:15:34,687]  INFO {org.wso2.carbon.core.init.CarbonServerManager} -  Starting Carbon initialization...
[2010-11-30 17:15:34,776]  INFO {org.wso2.carbon.core.init.CarbonServerManager} -  Creating super-tenant Axis2 ConfigurationContext
[2010-11-30 17:15:34,931]  INFO {org.apache.axis2.deployment.ClusterBuilder} -  Clustering has been disabled
[2010-11-30 17:15:35,050]  INFO {org.wso2.carbon.core.deployment.DeploymentInterceptor} -  Deploying Axis2 module: addressing-3.10 {super-tenant}
[2010-11-30 17:15:35,174]  INFO {org.apache.axis2.transport.tcp.TCPTransportSender} -  TCP Sender started
[2010-11-30 17:15:35,406]  INFO {org.wso2.carbon.core.deployment.DeploymentInterceptor} -  Deploying Axis2 service: version {super-tenant}
[2010-11-30 17:15:35,719]  INFO {org.apache.axis2.deployment.DeploymentEngine} -  Deploying Web service: Version.aar - file:/home/user/wso2carbon-3.1.0/
    repository/deployment/server/axis2services/Version.aar
[2010-11-30 17:15:35,753]  INFO {org.wso2.carbon.core.init.CarbonServerManager} -  Completed super-tenant Axis2 ConfigurationContext creation in 0.977 sec
[2010-11-30 17:15:35,885]  INFO {org.apache.axis2.deployment.ModuleDeployer} -  Deploying module: addressing-1.6-wso2v3 - file:/home/user/wso2carbon-3.1.0/repository/deployment/client/modules/addressing-1.6-wso2v3.mar
[2010-11-30 17:15:35,890]  INFO {org.apache.axis2.transport.tcp.TCPTransportSender} -  TCP Sender started
[2010-11-30 17:15:36,604]  INFO {org.wso2.carbon.core.init.CarbonServerManager} -  Repository       : /home/user/wso2carbon-3.1.0/repository/
    deployment/server/
[2010-11-30 17:15:36,643]  INFO {org.wso2.carbon.core.internal.permission.update.PermissionUpdater} -  Permission cache updated for tenant 0
[2010-11-30 17:15:36,645]  INFO {org.wso2.carbon.core.init.CarbonServerManager} -  ConfigurationContextService registered in 41ms
[2010-11-30 17:15:36,651]  WARN {org.apache.axis2.engine.ListenerManager} -  ConfigurationContext provided for the ListenerManager initialization is null.
    ListenerManager will not be initialized
[2010-11-30 17:15:36,651]  INFO {org.wso2.carbon.core.transports.http.HttpsTransportListener} -  HTTPS port       : 9443
[2010-11-30 17:15:36,651]  INFO {org.wso2.carbon.core.transports.http.HttpTransportListener} -  HTTP port        : 9763
[2010-11-30 17:15:37,530]  INFO {org.wso2.carbon.ui.internal.CarbonUIServiceComponent} -  Mgt Console URL  : https://10.100.1.141:9443/carbon/
[2010-11-30 17:15:37,540]  INFO {org.wso2.carbon.core.internal.StartupFinalizerServiceComponent} -  Started Transport Listener Manager
[2010-11-30 17:15:37,541]  INFO {org.wso2.carbon.core.internal.StartupFinalizerServiceComponent} -  Server           :  ${product.name}-${product.version}
[2010-11-30 17:15:37,541]  INFO {org.wso2.carbon.core.internal.StartupFinalizerServiceComponent} -  WSO2 Carbon started in 10 sec
Now to access the Web-based management console go to the https://localhost:9443/carbon in your browser. Login to the console using the default username and password

Running the Carbon in Apache Tomcat(Webapp Mode)

WSO2 Carbon can be deployed in application servers such as Apache Tomcat, JBOSS, WebSphere and WebLogic. In the below guide it explains how you can deploy Carbon, in the popular servlet container : Apache Tomcat. The installation steps, that are given below are valid for any WSO2 product that uses Carbon as its core platform. Furthermore the installation steps are more or less the same for any other application server apart from the server specific configuration parameters.

Setting up the Environment and Tools

Download and install the Apache tomcar servlet container, version 7.x.x

Download the latest carbon distribution from the project home Carbon

Carbon Directory Structure

Unzip your freshly downloaded carbon binary package (wso2carbon-3.x.x.zip) in to local file system.You should see the below directory structure in your unzipped carbon distribution.
carbon distribution structure

Creating and Configuring the Carbon Repository

create a directory in your file system (we assume the directory name as <Carbon_Repository> from here onwards), which to be use as our carbon repository. First we have to populate our carbon repository with the artifacts, extracted from the binary distribution. copy the following directories from your carbon binary distribution in to your newly created carbon repository, wso2carbon-3.x.x/repository

wso2carbon-3.x.x/resources After populating with artifacts, the carbon repository looks like,
carbon repository directory structure
Now we have to update some configurations files found in the <Carbon_Repository>/repository/conf directory.

Note: below configurations use <Carbon_Repository> instead of the absolute path to previously created carbon repository directory. The user should replace the <Carbon_Repository> with the appropriate absolute path, according to their local directory structure. 1. Configuring the transports (http and https ports):

Edit the <Carbon_Repository>/repository/conf/axis2.xml as follows.
        <transportReceiver name="http" class="org.wso2.carbon.core.transports.http.HttpTransportListener">
        <parameter name="port">8080</parameter>

        <transportReceiver name="https" class="org.wso2.carbon.core.transports.http.HttpsTransportListener">
        <parameter name="port">8443</parameter>
Here we have selected the ports 8080 and 8443 as the respective ports for http and https. admin can decide the ports they are going to use & chage the configuration files accordingly.

2. Configuring the carbon.xml

Edit the <Carbon_Repository>/repository/conf/carbon.xml as follows.
         <WebContextRoot>/crbn</WebContextRoot>
         <ServerURL>https://localhost:8443/crbn/services/</ServerURL>
3.Configuring the registry.xml

Edit the <Carbon_Repository>/repository/conf/registry.xml as follows.
<url>jdbc:h2:<Carbon_Repository>/repository/database/WSO2CARBON_DB;DB_CLOSE_ON_EXIT=FALSE</url>
4.Configuring the usr-mgt.xml

Edit the <Carbon_Repository>/repository/conf/user-mgt.xml as follows.
<Property name="url">jdbc:h2:<Carbon_Repository>/repository/database/WSO2CARBON_DB;DB_CLOSE_ON_EXIT=FALSE</Property>

Creating and Configuring the Carbon Web App (.war file)

Create a new Directory in your local file sytem (we assume the directory name as <WAR_DIR> from here onwards). copy the WEB-INF directoy found under wso2carbon-3.x.x/lib/core in to the newly created WAR-DIR directory. Now the WAR-DIR should have the directory structire similar to,
carbon web archive directory structure
To enable proper carbon related logging , copy the log4j.properties file found in wso2carbon-3.x.x/lib/ in to the <WEB_DIR>/WEB-INF/classes directory. Now it is time to pack the the our web app as a wep application archive (.war) file. In the command shell navigate to the WAR_DIR and execute the command; $> jar -cvf ./carbon.war ./* This will create a archive names carbon.war in the WAR_DIR directory and we are going to deploy that archive in out Apache Tomcat installation.

Configuring Apache Tomcat

Here we are using the https to access the management console of the carbon web app. Hence we have to specify the java key store file to be used by the Tomcat installation. Open the file, <CATALINA_HOME>/conf/server.xml (the Apache Tomcat installation root directory is identified as the CATALINA_HOME) update the server.xml as shown follows.
       <Connector SSLEnabled='true' keystoreFile='<Carbon_Repository>/resources/security/wso2carbon.jks' keystorePass='wso2carbon'
       maxSpareThreads='76' port='8443' protocol='HTTP/1.1' maxThreads='150' secure='true' scheme='https' sslProtocol='TLS' clientAuth='false'/>
  

Final Steps

1. Set the CARBON_HOME environment variable in your OS.

$> export CARBON_HOME= (absolute path to the <Carbon_Repository>)>

2. copy the previously created carbon.war file in to CATALINA_HOME/webapps directory.

3. Start Apache Tomcat.

4. Open your browser & go to the URL https://localhost:8443/crbn/carbon

Using the WSO2 Carbon Management Console

WSO2 Carbon management console is a Web based console powered by JSP and AJAX which enables system administrators to interact with a running Carbon instance, without having to touch any underlying configuration files. The management console allows the users to configure, manage the system. We recommend using Mozilla Firefox 3, 3.5 or Internet Explorer 7, 8 to access the WSO2 Carbon management console. Please note that your browser must be JavaScript enabled to take the full advantage of the management console. To access the Carbon management console fire off you Web browser and navigate to https://<Server Host>:<Server Port>/<Context>. If you are running the Web browser on the same machine as the Carbon you may use 'localhost' as the server host. The default port and the context for the Carbon management console are '9443' and 'carbon' respectively. If you entered the URL correctly you will be taken to the management console's login page. On the login page enter 'admin' as the username and the password to login to the system. You can change user credentials and even add new users once you login. Controls and wizards in the Carbon management console are pretty much self explainatory. However if you are having trouble finding your way in the management console, click on the 'Help' link at the top right corner of any page to access context sensitive help. Please note that the management console makes use of the default HTTPS servlet transport which is configured in the CARBON_HOME/repository/conf/mgt-transports.xml file. It is important that this transport is always properly configured in the mentioned file. Otherwise the management console might be inaccessible to the users.

User Management

You can manage user and roles in the system by user management facility available in the web-based management console. Click on User Management menu from left. Please refer the documentation on managing users for details.

Configuring User Stores

Please refer this guide which talks about user store configuration.

Setting Up Logging

A properly configured logging system is vital in identifying errors, security threats and usage patterns. WSO2 Carbon uses a log4j based logging mechanism through Apache Commons Logging facade library. The log4j.properties file which governs how logging is performed by the server can be found in CARBON_HOME/lib directory. By default WSO2 Carbon comes with the following log appenders configured. Log Levels

Installing and Managing Features

New features can be easily installed into the Carbon by using the 'WSO2 Carbon Feature Manager' that comes with the Carbon. 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 Carbon runtime. You can also uninstall existing features of the Carbon and come up with a customized version of WSO2 Carbon tailored to meet your requirements. To use the Feature manager, login to the management console and click on 'Feature Management' under the 'Configure' menu. Go to the 'Settings' tab and click on 'Manage Repositories'. Click 'Add New Repository' and specify the P2 repository to which you wish to connect to. The official WSO2 P2 repository is available over http://dist.wso2.org/p2/carbon/releases/3.1.0/. Once the repository is configured go to the 'Available Features' tab to browse through the features and get them installed to the Carbon. The installation of a feature can take a while depending on the network bandwidth and hardware configuration available. Once a feature has been successfully installed you will be prompted to logout and restart the Carbon. If you wish to uninstall an existing feature go to the 'Installed Features' tab, select the features to be uninstalled and click on 'Uninstall' at the bottom of the page.

Adding External Dependencies to the System

This is clearly explaing in an article hosted WSO2 Oxygen Tack. Please refer How to Add External Jar Libraries to WSO2 Carbon based products.