mPower Server

The mPower server runs the software for ChannelIT, LinkIT, and ServIT--the API, web services, and end-user web applications used with LeasePak.

This document assumes you have a working knowledge of either Apache/Tomcat or J2EE and does not cover the installation of either web server. Contact your MSI representative for more information.

System Requirements

Review the mPower Server hardware and software requirements. You must install and configure all required software before installing the mPower program files.

Apache/Java/Tomcat Configuration for mPower

Apache

Modify the file httpd.conf as shown below, substituting your values as necessary

# optional READ APACHE DOCS!!!!!!
ServerTokens Prod
		 
# optional READ APACHE DOCS!!!!!!
ServerSignature Off

# optional -> directory index should already exist and be set to 
# something like index.html index.htm I suggest adding index.jsp 
# as well
DirectoryIndex   index.jsp
		
# path to YOUR modjk module it may be mod_jk.so if UNIX/Linux/BSD
LoadModule jk_module modules/mod_jk.so

The following applies to Apache 1 users only. Apache 2 users: place the mod_jk.conf file in your conf.d directory and it will be automatically included.

# path to the mod jk config file
Include "<path to mod_jk config>conf/mod_jk.conf"

		
# these are some SSL settings for Apache
# SSL 
SSLMutex sem
SSLRandomSeed startup builtin
SSLSessionCache none
		
ErrorLog logs/ssl.log
		
# this line is optional
# at MSI we wanted all requests to mpower to be redirected to the mpower URL
RedirectMatch permanent    http\:*/mpower*       https://<web server name>/mpower
		
# note both above and here the webserver name should be changed 
<VirtualHost <webserver name>:443>
    SSLEngine On
    SSLCertificateFile conf/ssl/server.crt
    SSLCertificateKeyFile conf/ssl/server.key
</VirtualHost>

# also needed it a directory for mpower documents from dxGen
# something like  
Alias /mpower_docs "/var/www/httpd/mpower_docs"
<Directory "/var/www/httpd/mpower_docs ">
    AllowOverride None
    Options None
    Order allow,deny
    Allow from all
</Directory>

mod_jk

The following applies to mod_jk only, not mod_jk2. Refer to your mod_jk2 documentation for the corresponding configurations. Contact your MSI representative for more information.

Modify the file mod_jk.conf as shown below, substituting your values as necessary

# CHANGE THE PATHS TO MEET YOUR SYSTEM OR IT WONT WORK
<IfModule mod_jk.c>

SetEnv JAVA_HOME "/usr/java/j2sdk1.4.2_02/"
SetEnv CLASSPATH
"/var/tomcat4/common/lib;$JAVA_HOME/lib/tool.jar;/var/tomcat4/mpower/WEB-INF
/classes"

Alias /mpower "/var/tomcat4/webapps/mpower"
<Directory "/var/tomcat4/webapps/mpower">
    SSLRequireSSL
    Options Indexes FollowSymLinks
</Directory>

JkMount /mpower/servlet/* ajp13
JkMount /mpower/*.jsp ajp13
JkMount /mpower/*.do ajp13

<Location "/mpower/WEB-INF/">
    AllowOverride None
    deny from all
</Location>

</IfModule>

JkWorkersFile "/etc/httpd/conf/workers.properties"
JkLogFile "/var/tomcat4/logs/mod_jk.log"
#
JkLogLevel debug

Tomcat

If necessary, configure the following files to make sure you have the correct connector in Tomcat.

server.xml

<!-- MAKE SURE THAT YOU HAVE THE RIGHT CONNECTOR -->
<Connector className="org.apache.coyote.tomcat4.CoyoteConnector" acceptCount="10" 
    bufferSize="2048" compression="off" connectionLinger="-1" connectionTimeout="20000" 
    debug="0" disableUploadTimeout="false" enableLookups="true" maxKeepAliveRequests="100" 
    maxProcessors="75" minProcessors="5" port="8009" 
    protocolHandlerClassName="org.apache.jk.server.JkCoyoteHandler" proxyPort="0" 
    redirectPort="8443" scheme="http" secure="false" tcpNoDelay="true" 
    useURIValidationHack="false"> <Factory className="org.apache.catalina.net.DefaultServerSocketFactory"/>
</Connector>

To use ServIT (customer self service) and enable the sending of e-mail, you must modify server.xml to point mail.smtp.host to the actual e-mail host servIT will use. Modify the ResourceParams section as follows:

<ResourceParams name="mail/Session">
	<parameter>
    	<name>mail.smtp.host</name>
    	<value>localhost</value>
  	</parameter>
</ResourceParams>

where localhost is the mail.smtp.host servIT will use, and verify that the Tomcat server can connect to the specified host.

workers.properties

Refer to the Tomcat documentation to ensure that this file is set up correctly for your system.

mPower Installation for Apache/Java/Tomcat

To install and configure the mPower software:

Make sure Tomcat is running
Copy the file mpower.war to the CATALINA_HOME/webapps directory
Tomcat should deploy the file automatically. If it doesn't, restart Tomcat

If Tomcat still doesn't deploy the file, run the following commands:

cd CATALINA_HOME/webapps
mkdir mpower-
cd mpower
$JAVA_HOME/bin/jar -xvf (path to war file)/mpower-.war

This will deploy the file.

Use chown -R owner:group on the mpower directory and all its contents (including subdirectories and contents), where owner:group is the Tomcat user and corresponding group.

ChannelIT and ServIT (the end-user interfaces) will not work properly unless the Tomcat user (and corresponding group) is set as the owner:group of the mPower files.

LinkIT Users: API Deployment for Apache/Java/Tomcat

If you are using the LeasePak API, create a Bourne shell script similar to the following, using your directories, host name, and port number:

#! /bin/sh

# this is the web service you are going to deploy
DEPLOYFILE=$1

# the name of the contextroot
SERVICE_NAME=mpower-

# the directory you created
SERVICE_DIR=mpower-

# the name of the host
HOST=http://mpower.mccue.com

# the port that the service is on default install is 8080
PORT=8080

#tomcat4 INSTALL_BASE
TOMCAT_BASE=/opt/tomcat4

# base path to java home
JAVA_HOME=/opt/java

# mpower base is the location of the actual service on the filesystem
MPOWER_BASE=$TOMCAT_HOME/webapps/$SERVICE_DIR

# mpower libs is the location within mpower_base of the api required libraries
MPOWER_LIBS=$MPOWER_BASE/WEB-INF/lib

# this should not change
CLASSPATH=$JAVA_HOME/lib/tools.jar
for  APIFILE in $MPOWER_LIBS/*.jar ; do
    CLASSPATH=$CLASSPATH:$APIFILE
done

$JAVA_HOME/bin/java -classpath "$CLASSPATH" org.apache.axis.client.AdminClient -l$HOST:$PORT/$SERVICE_NAME/services/AdminService $DEPLOYFILE

Name the script mpower_ws.sh and save it to your mPower WEB-INF/config directory. Then cd to your WEB-INF/config directory and run the script for each service you wish to deploy:

mpower_ws.sh LPClient/deploy.wsdd

mpower_ws.sh LPApplication/deploy.wsdd

mpower_ws.sh LPAsset/deploy.wsdd

etc. You should only have to do this once, unless additional methods are added to a service. Contact your MSI representative for more information.

J2EE Configuration for mPower

Debug logging in the web server and API is unavailable with J2EE.

Edit the server.policy file, by default located in /opt/SUNWappserver/domains/domain1/config.

Find the grant section--that is, the section that begins grant {, with no additional text or data between the word grant and the right brace.

// Basic set of required permissions granted to all remaining code
grant {
        permission java.lang.RuntimePermission  "loadLibrary.*";
        permission java.lang.RuntimePermission  "queuePrintJob";
        permission java.net.SocketPermission    "*", "connect";
        permission java.io.FilePermission       "<<ALL FILES>>", "read,write,delete";

        // work-around for pointbase bug 4864405
        permission java.io.FilePermission "${com.sun.aas.instanceRoot}${/}lib${/}databases${/}-", "delete";
        permission java.io.FilePermission "${java.io.tmpdir}${/}-", "delete";

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

        permission java.lang.RuntimePermission  "getClassLoader";
        permission java.lang.RuntimePermission  "createClassLoader";
        permission java.lang.RuntimePermission  "modifyThreadGroup";
};

The above example includes all the required permissions for mPower to run on J2EE. If needed, make these changes to your file:

For the file beginning permission java.io.FilePermission, change to

permission java.io.FilePermission       "<<ALL FILES>>", "read,write,delete";

For the file beginning permission java.util.PropertyPermission, change to
```
permission java.util.PropertyPermission "*", "read,write";
```

Add the following two lines, anywhere before the end (};) of the section

permission java.lang.RuntimePermission  "getClassLoader";
permission java.lang.RuntimePermission  "createClassLoader";

After saving the edited file, restart the J2EE server to register the changes. To restart the server, use the following commands in sequence:

/opt/SUNWappserver/bin/asadmin stop-domain
/opt/SUNWappserver/bin/asadmin start-domain

mPower Installation for J2EE

To install and configure the mPower software

If needed, restart the J2EE server to register changes to the server.policy file
mkdir -p /opt/msi//mpower-
Copy the file mpower-.war to any location on the server except /opt/msi//mpower-
cd /opt/msi//mpower-
$JAVA_HOME/bin/jar -xvf (path to war file)/mpower-.war
cd /opt/SUNWappserver/bin
As root, run the command asadmin start-domain to make sure the domain is running
Then run the following command to deploy mPower:
```
asadmin deploydir --user admuser --password admpasswd --host host --port port --contxtroot mpower_root path_to_mpower_app
```
where admuser is the admin user account name, admpasswd is the admin user account password, host is the name of the mPower server host machine, port is the mPower port number, mpower_root is the mPower URL root directory following the domain (for example, in www.mccue.com/mpower, /mpower (including the beginning slash), is the root), and path_to_mpower_app is the actual and full path to the mPower application files (for example, /opt/msi//mpower).

In the above command, each option is preceded by a double hyphen (--).

LinkIT Users: API Deployment for J2EE

If you are using the LeasePak API, create a Bourne shell script similar to the following, using your directories, host name, and port number:

#! /bin/sh

# this is the web service you are going to deploy
DEPLOYFILE=$1

# the name of the contextroot specified above
SERVICE_NAME=mpower-

# the directory you created
SERVICE_DIR=mpower-

# the name of the host
HOST=http://mpower.mccue.com

# the port that the service is on default install is 8080
PORT=8080

#j2ee INSTALL_BASE
J2EE_BASE=/opt/SUNWappserver

# base path to java home, for j2ee it is in the j2ee directory
JAVA_HOME=$J2EE_BASE/jdk

# unless you created your own domain then this should be correct, otherwise change domain1 to the name of your new domain
# mpower base is the location of the actual service on the filesystem
MPOWER_BASE=$J2EE_BASE/domains/domain1/applications/backup/j2ee-modules/$SERVICE_DIR

# mpower libs is the location within mpower_base of the api required libraries
MPOWER_LIBS=$MPOWER_BASE/WEB-INF/lib

# this should not change
CLASSPATH=$JAVA_HOME/lib/tools.jar
for  APIFILE in $MPOWER_LIBS/*.jar ; do
    CLASSPATH=$CLASSPATH:$APIFILE
done

if [ ! -f  "$J2EE_BASE/lib/wsdl4j.jar" ] ; then
    echo "Copying wsdl4j to j2ee common lib!"
    cp $MPOWER_LIBS/wsdl4j.jar $J2EE_BASE/lib/
fi

$JAVA_HOME/bin/java -classpath "$CLASSPATH" org.apache.axis.client.AdminClient -l$HOST:$PORT/$SERVICE_NAME/services/AdminService $DEPLOYFILE

Name the script mpower_ws.sh and save it to your mPower WEB-INF/config directory. Then cd to your WEB-INF/config directory and run the script for each service you wish to deploy:

mpower_ws.sh LPClient/deploy.wsdd

mpower_ws.sh LPApplication/deploy.wsdd

mpower_ws.sh LPAsset/deploy.wsdd

etc. You should only have to do this once, unless additional methods are added to a service. Contact your MSI representative for more information.

mPower Configuration

mPowerd Daemon

Make sure the mPowerd daemon is properly installed on your LeasePak server.

`leasepak.xml`

Edit the following parameters in leasepak.xml, located in the mpower directory:

<TCP_IP_ADDRESS>leasepak_server</TCP_IP_ADDRESS>
<ENVIRONMENT>leasepak_environment</ENVIRONMENT> 
<PORT>mPowerd_port</PORT>

where leasepak_server is the IP address or name of your LeasePak server, leasepak_environment is the name of the LeasePak environment, and mPowerd_port is the TCP port number for the mPowerd daemon (not the leasepakd daemon).

`web.xml`

Edit the web.xml file, located in the mpower/WEB-INF directory.

First, find the following element group:

<!-- this is time in minutes, and cannot be set to less than 5 minutes -->
<env-entry>
<env-entry-name>LPCODES_UPDATE_INTERVAL</env-entry-name>
<env-entry-value>value</env-entry-value>
<env-entry-type>java.lang.String</env-entry-type>
</env-entry>

If you are using LinkIT (the LeasePak API) without ChannelIT or ServIT (the end-user interfaces), set value to 0 to optimize server performance by preventing updates to the mPower server's LPCODES.TXT file.

If, however, you are using ChannelIT or ServIT, MSI recommends setting value to a minimum of 60 (minutes). If you add or change LeasePak codes frequently, you can set this number lower, but no lower than 5 (minutes).

Next, find the customization section of the file and edit as needed:

<!-- ************************************** -->
<!-- site customize here -->
<!-- ************************************** -->

<!-- note these two may need site customization -->
<!-- this is the API username -->
<env-entry>
<env-entry-name>apiuid</env-entry-name>
<env-entry-value>api_username_value</env-entry-value>
<env-entry-type>java.lang.String</env-entry-type>
</env-entry>

<!-- this is the API password -->
<env-entry>
<env-entry-name>apipwd</env-entry-name>
<env-entry-value>api_password_value</env-entry-value>
<env-entry-type>java.lang.String</env-entry-type>
</env-entry>

<!-- this is the URL to the DocGen web service -->
<env-entry>
<env-entry-name>docgen_endpoint</env-entry-name>
<env-entry-value>http://host:port/dxGen-/services/DocGenWsdl</env-entry-value>
<env-entry-type>java.lang.String</env-entry-type>
</env-entry>

<!-- if you are using the customer self service and want the email to work,
        set this to the smtp mail host.  After setting this tomcat must be restarted. -->
<env-entry>
<env-entry-name>smtp_mail_host</env-entry-name>
<env-entry-value>mail_host.domain.suffix</env-entry-value>
<env-entry-type>java.lang.String</env-entry-type>
</env-entry>

<!-- ************************************** -->
<!-- site customize ends here -->
<!-- ************************************** -->

The API username is the account you have designated for use with the mPower server (ChannelIT, LinkIT, or ServIT) and the API password is the LeasePak client string password created for the account.

The information contained in this document is the property of McCue Systems, Inc. Use of the information contained herein is restricted. Conditions of use are subject to change without notice. McCue Systems, Inc. assumes no liability for any inaccuracy that may appear in this document; the contents of this document do not constitute a promise or warranty. The software described in this document is furnished under license and may be used or copied only in accordance with the terms of said license. Unauthorized use, alteration, or reproduction of this document without the written consent of McCue Systems, Inc. is prohibited.