Lost in Time!!!: WSO2 Stratos Installation Guide

WSO2 Stratos is a platform as a service offering by WSO2. It includes the full middleware components stack by WSO2 that’s optimized to run in a cloud environment. Public offering of WSO2 Stratos can be accessed by visiting cloud.wso2.com. WSO2 Stratos can also be downloaded and configured to be run on a private cloud within an organization. This guide will help you to run WSO2 Stratos on your private cloud setup.

2 System requirements

WSO2 Stratos currently runs on top of Ubuntu Enterprise Cloud (UEC). This guide assumes that you’ve successfully configured Ubuntu Enterprise Cloud on your data center. The virtual machines that will be running all the Stratos services, will be running on Ubuntu Linux. Although this can be any operating system, we recommend you to have Ubuntu instances for the setup.

3 WSO2 Stratos overview

Before configuring WSO2 Stratos, let’s briefly look at the role of each service. WSO2 Stratos comes with three mandatory services. These are tightly coupled to each other that you have to have these services setup in order to have a minimal WSO2 Stratos installation.

3.1 Mandatory services

Mandatory services provide an infrastructure framework, which all other Stratos services will depend on. These three services together will provide administrative, authentication, measurement of service usage for all other Stratos services.

3.1.1 Cloud Manager

Cloud Manager acts as an administrative dashboard for other Stratos services. Cloud Manager handles registering of tenants and monitors resource usage for billing and metering purposes. Once you register your tenant, you can login as the tenant administrator and enable/disable optional services for all your tenants.

3.1.2 Governance Registry

Governance registry is a composition of three separate registries. Each service will be using three different registries to store different categories of data. Following figure shows how each service is wired to these registries.

Each Stratos service (ESB, Mashup, Application server etc.) can be clustered so that they can act smoothly under heavy loads. Each node in a cluster, for example like the nodes in the Mashup server cluster in the figure above, is configured with their own local registries. This registry will be storing data which is specific to one single Mashup server instance.

A config registry is used to store data that’s shared within a cluster.

A governance registry is used by all nodes across clusters to store all resource information.

3.1.3 Identity Server

All identity related information is stored in the Identity Server. Stratos Manager as well as all other Stratos services will be talking to the Identity Server for authentication and authorization operations. Identity Server will automatically handle single sign on between all Stratos services.

3.2 Optional services

Once you have installed the three essential services, depending on your requirements, you can install all or a selective set of services from the WSO2 middleware stack. Like Application Server, ESB, Mashup server etc.

4 Installation

This guide assumes you have a working installation of Ubuntu Enterprise Cloud in your datacenter with sufficient resources to create a set of virtual machines.

4.1 MySQL server installation

It’s advisable to have a separate instance to host the MySQL database. Create an instance with MySQL server. To run Stratos, you need following four databases,

Stratos database
Billing database
BAM database (only needed if you’re using BAM service)
BPS database (only needed if you’re using BPS service)

You can find the SQL script for creating the tables in Stratos database under <Stratos manager>/dbscripts/mysql.sql.

To create the tables in billing database run <Stratos manager>/dbscripts/billing-mysql.sql and <Stratos manager>/dbscripts/bam/sql/bam_schema_mysql.sql. This creates all the tables necessary for billing and metering functionality.

If you’re using BAM services, tables needed for the BAM database can be created using <BAM service>/dbscripts/bam/bam_schema_mysql.sql.

If you’re using BPS services, tables needed for the BPS database can be created using <BPS service>/dbscripts/bps/bpel/mysql.sql.

If you want to cluster MySQL please refer to WSO2 Stratos MySQL Clustering Guide.

4.2 Installing Stratos services

There are configuration changes that need to be made for all the Stratos services. These configuration settings will be common across all services. Hence, we’re discussing them first and then will be going to specific configuration steps needed for each service.

You have to create another Eucalyptus image which will be used to start Stratos services.

Make sure you have the following configurations.

Install the latest version of Sun JDK.
Install Java Cryptography Extensions (JCE) for your JDK

4.2.1 Common configurations

We’re going to discuss the common configuration options necessary for every Stratos service. You should follow these steps when you’re configuring any Stratos service. Then proceed to the section that further describes the specific configuration options for each service.

Throughout this document, STRATOS_HOME refers to the location where you’ve unzipped a given Stratos service artifact.

4.2.1.1 carbon.xml

In “<STRATOS_HOME>/repository/conf/carbon.xml” there are two properties that you have to change. ServerURL, HostName.

ServerName should contain the fully qualified domain name of the instance that you’ll be referring within your network.

<ServerURL>https://identity.example.com${carbon.context}/services/</ServerURL>

HostName should also contain the fully qualified domain name that you’ll be using.

<HostName>identity.example.com</HostName>

4.2.1.2 axis2.xml

You have to modify axis2.xml to give configuration option for the mail transport. Please give your correct mail server config for the following XML snippet. This mail transport will be used to send notification from Stratos services.

<parameter name="mail.smtp.host">mail.example.org</parameter>

<parameter name="mail.smtp.starttls.enable">false</parameter>

<parameter name="mail.smtp.user">username</parameter>

<parameter name="mail.smtp.password">secret</parameter>

<parameter name="mail.smtp.from">cloud-noreply@example.com</parameter>

</transportSender>

4.2.1.3 mgt-transport.xml

You can change the ports of the corresponding Stratos service to whatever the ports that you’ll intend to run it on. If you’re fronting your services with a web server so that your services will be accessed through the standard HTTP and HTTPS ports you need to change the proxyPort parameter too.

...

4.2.1.4 user-mgt.xml

Modify “user-mgt.xml” to give the Stratos database connection parameters. And include the SAML2SSOConfiguration snippet for single sign on just after AuthorizationManager.

“stratos_db” in the following configuration refers to the Stratos database.

<Property name="url">jdbc:mysql://mysql.example.com:3306/stratos_db?autoReconnect=true</Property>

<Property name="userName">username</Property>

<Property name="password">password</Property>

<Property name="driverName">com.mysql.jdbc.Driver</Property>

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

<ManagerHomepage>https://cloud.example.com/</ManagerHomepage>

<LoginPage>/carbon/tenant-login/login_ajaxprocessor.jsp</LoginPage>

<ServiceProviderID>SERVICE_NAME</ServiceProviderID>

https://identity.cloud.example.com/samlsso

</IdentityProviderSSOServiceURL>

</SAML2SSOConfiguration>

In the above configuration SERVICE_NAME should be the same as the “Name” setting given in corresponding server’s carbon.xml and IdentityServer's sso-idp-config.xml. Make sure to replace theIdentityProviderSSOServiceURL part with correct URL associated with your Identity Server instance and ManagerHomepage with correct URL of stratos manager.

4.2.1.5 registry.xml

For all the services other than the Governance Registry, following configuration should be applied. Make sure to replace the SERVICE part with each Stratos service name that you’ll be installing.stratos_db in following snippet points to the Stratos database.

Add the following snippet to registry.xml and change database settings to point to stratos database, change “/_system/SERVICEConfig” to correct stratos service (E.g: /_system/esbConfig for esb, /_system/identityConfig for Identity Server, etc.)

<url>jdbc:mysql://mysql.example.com:3306/stratos_db?autoReconnect=true</url>

<userName>username</userName>

<password>password</password>

<driverName>com.mysql.jdbc.Driver</driverName>

</dbConfig>

<id>stratos</id>

<dbConfig>stratosMountRegistry</dbConfig>

<readOnly>false</readOnly>

</remoteInstance>

<!--

This is the mount path for the config registry. In the Stratos Manager and Stratos

Application server, config registry should point to a MySQL database. Make sure to omit

this section in the Stratos Manager and Appserver installations. The correct setting

is outlined in the specific configuration section below.

-->

<instanceId>stratos</instanceId>

<targetPath>/_system/SERVICEConfig</targetPath>

</mount>

<instanceId>stratos</instanceId>

<targetPath>/_system/governance</targetPath>

</mount>

4.2.1.6 MySQL driver setup

Download the MySQL JDBC driver from - http://dev.mysql.com/downloads/connector/j/
Copy the MySQL driver .jar file to <STRATOS_HOME>/repository/components/lib

4.2.1.7 wrapper.conf

If you’re fronting with Apache you need to change the ports on wrapper.conf as well.

wrapper.java.additional.11=-Dcarbon.https.port=443

wrapper.java.additional.12=-Dcarbon.http.port=80

wrapper.java.additional.13=-Dcarbon.use.registry.repo=true

Check existing “wrapper.java.additional.*” and adjust above numbers (11, 12, 13). The numbers should be sequence and there should not be any gaps or any duplicates.

4.2.1.8 Increasing the number of open file descriptors

Increase the number of open file descriptors to 100000. modify wso2server.sh, daemon.sh, wso2cloud-server.sh and include the line,

ulimit -n 100000

4.2.2 Specific configurations

There are common configuration options that you need to do regardless of what Stratos services you’re trying to install are. Those have been discussed in the previous section. This section describes the configurations which are specific to certain cloud services. When you’re installing a Stratos service, you have to first complete the common configuration options part and then continue with the specific configuration options outlined in this section.

4.2.2.1 Stratos Manager

1. <Stratos Manager>/repository/conf/billing-config.xml

Database configuration for the billing engine billing_db in the following configuration refers to the billing database.

<url>jdbc:mysql://mysql.example.com:3306/billing_db?autoReconnect=true</url>

<userName>username</userName>

<password>password</password>

<driverName>com.mysql.jdbc.Driver</driverName>

</dbConfig>

2. <Stratos Manager>/repository/conf/tenant-reg-agent.xml

The following configuration is used to activate tenants in each of the services. It should include the services you intend to use and super admin username, password of those services.

<serverUrl>https://governance.example.com/services/</serverUrl>

<userName>admin</userName>

<password>password</password>

</server>

<serverUrl>https://identity.example.com/services/</serverUrl>

<userName>admin</userName>

<password>password</password>

</server>

<serverUrl>https://gadget.example.com/services/</serverUrl>

<userName>admin</userName>

<password>password</password>

</server>

<serverUrl>https://appserver.example.com/services/</serverUrl>

<userName>admin</userName>

<password>password</password>

</server>

</tenantRegListenerServers>

3. <Stratos Manager>/repository/conf/cloud-services-desc.xml

This file should include URL of the services, and their discriptions. It should include compulsory services (Stratos Manager, Stratos Governance and Stratos Identity) and any optional services of your choice.

</cloudService>

<label>Cloud Governance</label>

<description>Governance in the cloud.</description>

<icon>

https://localhost:9443/cloud-services-icons/governance.gif

</icon>

</cloudService>

<label>Cloud Identity</label>

<icon>

https://localhost:9443/cloud-services-icons/identity.gif

</icon>

<description>Identity in the cloud.</description>

</cloudService>

</cloudServices>

4. <Stratos Manager>/repository/deployment/server/dataservices/*.dbs

Modify “bamDataSource” of above files and point the billing database.

<property name="org.wso2.ws.dataservice.driver">com.mysql.jdbc.Driver</property>

jdbc:mysql://mysql.example.com:3306/billing_db?autoReconnect=true

</property>

<property name="org.wso2.ws.dataservice.user">username</property>

<property name="org.wso2.ws.dataservice.password">password</property>

<property name="org.wso2.ws.dataservice.autocommit">false</property>

</config>

Also modify “registryDataSource” of <Stratos Manager>/repository/deployment/server/MeteringSummaryGenerationDS.dbs and point to stratos database.

<property name="org.wso2.ws.dataservice.driver">com.mysql.jdbc.Driver</property>

jdbc:mysql://mysql.example.com:3306/stratos_db?autoReconnect=true

</property>

<property name="org.wso2.ws.dataservice.user">username</property>

<property name="org.wso2.ws.dataservice.password">password</property>

<property name="org.wso2.ws.dataservice.autocommit">false</property>

</config>

5. <Stratos Manager>/repository/conf/email-*.xml

All the configuration files starting with email- should be edited to include the correct Stratos Manager URL.

6. Copy the MySQL driver file (see the common configurations section) to lib/realm. So in stratos manager, MySQL driver file should be copied to two locations (repository/components/lib andlib/realm).

7. Local registry in <Stratos Manager>/repository/conf/registry.xml should point to a MySQL database. You can create the database using <Stratos Manager>/dbscripts/mysql.sql.

<url>jdbc:mysql://mysql.example.com:3306/manager_local_reg?autoReconnect=true</url>

<userName>username</userName>

<password>password</password>

<driverName>com.mysql.jdbc.Driver</driverName>

</dbConfig>

4.2.2.2 Services except Cloud Manager

Modify carbon.xml and give Stratos manager’s URL in following configuration, <BamServerURL>https://bam.cloud.example.com/services/</BamServerURL>

4.2.2.3 Identity Server

Modify sso-idp-config.xml, and add all compulsary services and any optional services.

Note that, the server name given in the <Issuer> should be same as the server name given in corresponding server's user-mgt.xml's <SAML2SSOConfiguration>.

<TenantRegistrationPage>https://cloud.example.com/carbon/tenant-register/select_domain.jsp</TenantRegistrationPage>

<Issuer>WSO2 Stratos Identity</Issuer>

<AssertionConsumerService>https://identity.example.com/acs</AssertionConsumerService>

</ServiceProvider>

<Issuer>WSO2 Stratos Governance</Issuer>

<AssertionConsumerService>https://governance.example.com/acs</AssertionConsumerService>

</ServiceProvider>

<Issuer>WSO2 Stratos Manager</Issuer>

<AssertionConsumerService>https://cloud.example.com/acs</AssertionConsumerService>

</ServiceProvider>

<Issuer>WSO2 Stratos Mashup Server</Issuer>

<AssertionConsumerService>https://mashup.example.com/acs</AssertionConsumerService>

</ServiceProvider>

<Issuer>WSO2 Stratos Gadgets</Issuer>

<AssertionConsumerService>https://gadget.example.com/acs</AssertionConsumerService>

</ServiceProvider>

<Issuer>WSO2 Stratos Application Server</Issuer>

<AssertionConsumerService>https://appserver.example.com/acs</AssertionConsumerService>

</ServiceProvider>

</ServiceProviders>

</SSOIdentityProviderConfig>

Modify identity.xml and change OpenIDServerUrl, OpenIDUserPattern and IdentityProviderURL to point to your identity service’s URL

<OpenIDServerUrl>https://identity.cloud.example.com/openidserver</OpenIDServerUrl>

<OpenIDUserPattern>https://identity.cloud.example.com/openid/</OpenIDUserPattern>

<IdentityProviderURL>https://identity.cloud.example.com/samlsso</IdentityProviderURL>

</SSOService>

4.2.2.4 Governance Registry

Modify registry.xml and remove existing dbConfig section. Then include the following configuration. The “stratos_db” in the following configuration refers to the Stratos database.

<url>jdbc:mysql://mysql.example.com:3306/registry_db?autoReconnect=true</url>

<userName>username</userName>

<password>password</password>

<driverName>com.mysql.jdbc.Driver</driverName>

<validationQuery>SELECT 1</validationQuery>

</dbConfig>

4.2.2.5 Application Server

Copy jaxws jars to repository/components/extensions (jars can be downloaded from http://www.java2s.com/Code/JarDownload/jaxws-rt.jar.zip andhttp://www.java2s.com/Code/JarDownload/jaxws-tools.jar.zip)
Copy the MySQL driver file (see the common configurations section) to lib/realm. So in Application Server MySQL driver file should be copied to two locations (repository/components/lib andlib/realm).
In repository/components/registry.xml the local registry should point to a MySQL database. Create the database using dbscripts/mysql.sql.

<url>jdbc:mysql://mysql.example.com:3306/appserver_local_reg?autoReconnect=true</url>

<userName>username</userName>

<password>password</password>

<driverName>com.mysql.jdbc.Driver</driverName>

</dbConfig>

4.2.2.6 Business Activity Monitor

Modify repository/deployment/server/dataservices/*.dbs and give correct username and password for the BAM database.

<property name="org.wso2.ws.dataservice.driver">com.mysql.jdbc.Driver</property>

jdbc:mysql://mysql.example.com:3306/bam_db?autoReconnect=true

</property>

<property name="org.wso2.ws.dataservice.user">username</property>

<property name="org.wso2.ws.dataservice.password">password</property>

<property name="org.wso2.ws.dataservice.autocommit">false</property>

</config>

4.2.2.7 Business Process Server

Make sure you have a file name datasources.properties in repository/conf/. Create it if it doesn’t exist.

synapse.datasources=bpsds

synapse.datasources.icFactory=com.sun.jndi.rmi.registry.RegistryContextFactory

synapse.datasources.providerPort=2199

synapse.datasources.bpsds.registry=JNDI

synapse.datasources.bpsds.type=BasicDataSource

synapse.datasources.bpsds.driverClassName=com.mysql.jdbc.Driver

synapse.datasources.bpsds.url=jdbc:mysql://mysql.example.com:3306/bps_db?autoReconnect=true

synapse.datasources.bpsds.username=username

synapse.datasources.bpsds.password=password

synapse.datasources.bpsds.dsName=bpsds

synapse.datasources.bpsds.maxActive=100

synapse.datasources.bpsds.maxIdle=20

synapse.datasources.bpsds.maxWait=60000

In your bps.xml make sure you have uncommented the data source name. The respective section should look like the following snippet.

<tns:DataBaseConfig mode="EXTERNAL">

<tns:DataSource name="bpsds">

<tns:JNDI contextFactory="com.sun.jndi.rmi.registry.RegistryContextFactory" providerURL="rmi://localhost:2199"/>

</tns:DataSource>

</tns:DataBaseConfig>

4.2.2.8 Data Services Server

If you are planning to expose any RDBMS other than MySQL, then you have to download corresponding JDBC driver and copy to repository/components/lib.

4.2.2.8 Enterprise Service Bus

Modify axis2.xml and include bind address, WSDL prefix for NHttp transport. Change value of those parameters with the URL of ESB service.

<parameter name="bind-address" locked="false">esb.cloud.example.com</parameter>

http://esb.cloud.example.com:8280

</parameter>

</transportReceiver>

<parameter name="bind-address" locked="false">esb.cloud.example.com</parameter>

https://esb.cloud.example.com:8243

</parameter>

<Location>resources/security/wso2carbon.jks</Location>

<Password>wso2carbon</Password>

<KeyPassword>wso2carbon</KeyPassword>

</KeyStore>

</parameter>

<Location>resources/security/client-truststore.jks</Location>

<Password>wso2carbon</Password>

</TrustStore>

</parameter>

</transportReceiver>

5 Signing JARs

If you want to restrict the users so that they will not be able to run any privileged operations, then you can sign the jars using your own key and allow only jars signed using the key to execute any privileged instructions. This can be specified in a security policy file. Create a file called sec.policy inside repository/conf/; Place the keystore inside resources/security.

In the snippet below, “your_keystore.jks” should be changed to your key store file name, “your_key_alias” should be changed with the key alias used to sign the jars.

keystore "file:${user.dir}/resources/security/your_keystore.jks", "JKS";

// ========== SYSTEM CODE PERMISSIONS =========================================

// These permissions apply to javac

grant codeBase "file:${java.home}/lib/-" {

permission java.security.AllPermission;

};

// These permissions apply to all shared system extensions

grant codeBase "file:${java.home}/jre/lib/ext/-" {

permission java.security.AllPermission;

};

// These permissions apply to javac when ${java.home] points at $JAVA_HOME/jre

grant codeBase "file:${java.home}/../lib/-" {

permission java.security.AllPermission;

};

// These permissions apply to all shared system extensions when

// ${java.home} points at $JAVA_HOME/jre

grant codeBase "file:${java.home}/lib/ext/-" {

permission java.security.AllPermission;

};

// ========= Carbon Cloud Server Permissions ===================================

grant {

permission java.net.SocketPermission "*:1-65535", "connect,resolve";

permission java.util.PropertyPermission "http.proxyHost", "read";

permission java.util.PropertyPermission "http.nonProxyHosts", "read";

permission java.util.PropertyPermission "adb.converterutil", "read";

permission java.lang.RuntimePermission "accessClassInPackage.*";

permission java.util.PropertyPermission "*", "read";

};

grant signedBy "your_key_alias" {

// permission java.util.PropertyPermission "*", "read";

// permission java.lang.RuntimePermission "*", "*";

// permission java.io.FilePermission "*", "*";

permission java.security.AllPermission;

};

grant CodeBase "file:${user.dir}/lib/core/-" {

permission java.security.AllPermission;

};

Also, specify the services to use above policy by including following lines in wrapper.conf

wrapper.java.additional.20=-Djava.security.manager=java.lang.SecurityManager

wrapper.java.additional.21=-Djava.security.policy=repository/conf/sec.policy

Check existing “wrapper.java.additional.*” and adjust above numbers (20, 21). The numbers should be sequence and there should not be any gaps or any duplicates.

6 Caveats

When you’re deciding virtual disk sizes for your instances, Stratos BAM service will be having a significant growth of it’s database. It’s recommended that you maintain a separate database with plenty of disk space when configuring BAM.

You can also find the list of known issues from the issue tracker: https://wso2.org/jira/browse/STRATOS

http://wso2.org/project/stratos/1.0.0/WSO2StratosInstallationGuide.html

Lost in Time!!!

Sunday, September 4, 2011

WSO2 Stratos Installation Guide

No comments:

Post a Comment