WSO2 Carbon - System Administration Guide [ Documentation Index ]
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.
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)
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.
|
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.
|
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 |
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.
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
Download and install the Apache tomcar servlet container, version 7.x.x
Download the latest carbon distribution from the project home Carbon
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.
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 directory from your carbon binary distribution in to your newly created carbon repository.
wso2carbon-3.x.x/repository
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>
1. Create a new Directory in your local file system (we assume the directory name as <WAR_DIR> from here onwards). copy the WEB-INF directory found under wso2carbon-3.x.x/lib/core. in to the newly created WAR_DIR directory. Now the WAR_DIR should have the directory structure similar to,
2. 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.
3. Copy all libraries found in wso2carbon-3.x.x/lib/api/ directory into WAR_DIR/WEB-INF/lib directory.
Alternately you can execute the ant task, ant createWAR from the wso2carbon-3.x.x/bin which creates a WEB-INF with all the above steps applied.
4. 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 ./crbn.war ./*
This will create a archive names crbn.war in the WAR_DIR directory and we are going to deploy that archive in out Apache Tomcat installation.
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'/>
1. Set the CARBON_HOME environment variable in your OS.
$> export CARBON_HOME=(absolute path to the <Carbon_Repository>)
2. Set required memory limits as follows.
$> export JAVA_OPTS="-Xms256m -Xmx512m -XX:MaxPermSize=128m"
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
1. If you want to deploy JAX-WS services on your carbon server, you have to copy the JDK_HOME/lib/tools.jar into WAR_DIR/WEB-INF/lib directory.
2. If you are deploying WSO2 AppServer on Tomcat, it is recommended to delete org.wso2.carbon.webapp.mgt*.jar files (there are 3 jar files) from <Carbon_Repository>/repository/components/plugins directory.
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 explanatory. 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.
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.
Please refer this guide which talks about user store configuration.
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
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.
This is clearly explaining in an article hosted WSO2 Oxygen Tack. Please refer How to Add External Jar Libraries to WSO2 Carbon based products.