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.
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.
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,
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,
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.
- CARBON_CONSOLE - Console appender, as the name implies it appends log messages to the System.out
- CARBON_LOGFILE - File appender, appends log messages to a file(Writes the logs to CARBON_HOME/repository/logs/wso2-carbon.log)
- CARBON_MEMORY - Memory appender, Append log messages to circular buffer in memory and this buffer length can be configured
- CARBON_SYS_LOG - Syslog appender sends log messages to a syslog receiver.
Log Levels
- trace - developing only, can be used to follow the program execution.
- Debug - developing only, for debugging purpose
- Info - Production optionally, Course grained (rarely written information), I use it to
print that a configuration is initialized, a long running import job is starting and ending.
- Warn - Production, simple application error or unexpected behaviour. Application can
continue. I warn for example in case of bad login attemps, unexpected data during import jobs.
- Error - Production, application error/exception but application can continue. Part of the
application is probably not working.
- Fatal - Production, fatal application error, application cannot continue, for example
database is down.
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.