Kony MobileFabric Kony Messaging Services On-Premises Installation Guide - Linux Release 5.6 Document Relevance and Accuracy This document is considered relevant to the Release stated on this title page and the document version stated on the Revision History page. Remember to always view and download the latest document version relevant to the software release you are using.
Copyright 2013 by Kony, Inc. All rights reserved. August, 2014 This document contains information proprietary to Kony, Inc., is bound by the Kony license agreements and may not be used except in the context of understanding the use and methods of Kony Inc, software without prior, express, written permission. Kony, Empowering Everywhere, Kony MobileFabric, and Kony Visualizer are trademarks of Kony, Inc. Microsoft, the Microsoft logo, Internet Explorer, Windows, and Windows Vista are registered trademarks of Microsoft Corporation. Apple, the Apple logo, itunes, iphone, ipad, OS X, Objective-C, Safari, and Xcode are registered trademarks of Apple, Inc. Google, the Google logo, Android, and the Android logo are registered trademarks of Google, Inc. Chrome is a trademark of Google, Inc. BlackBerry, PlayBook, Research in Motion, and RIM are registered trademarks of BlackBerry. All other terms, trademarks, or service marks mentioned in this document have been capitalized and are to be considered the property of their respective owners. Copyright 2013 Kony, Inc. All rights reserved. Page 2 of 23
Revision History Date Document Version Description of Modifications/Release 12/02/2013 1.0 Initial Release 05/14/2014 1.2 Document Release for 5.6 06/02/2014 1.3 08/21/2014 1.4 Updated Troubleshooting section Added Note for "JDK 1.6 64 bit" in the section "Installing the KMS" Updated the complete Kony Messaging Services On-Premises Installation Guide Linux for 5.6.2 release Copyright 2013 Kony, Inc. All rights reserved. Page 3 of 23
Table of Contents 1. Introduction 5 1.1 Intended Audience 5 1.2 Typographical Conventions 5 1.3 Reference Documents 6 1.4 Contact Us 6 2. Prerequisites 7 2.1 Software Requirements 7 2.2 Hardware Requirements 7 2.3 Creating the Installation User for Linux 7 3. Corporate Firewall Settings 8 4. Pre-installation Tasks 10 4.1 Install JDK 1.7 or Higher Version 10 4.2 Install Java Environment and Configure JAVA_HOME 10 5. KMS Files 12 6. Installing KMS on Linux 13 6.1 Installation Procedure 13 7. Post Installation Tasks 21 7.1 Start KMS Server - Tomcat 21 7.2 Start KMS Server - JBoss 21 8. Troubleshooting 22 8.1 Error Message 22 8.2 Error Message 22 8.3 JBoss Server Behind Proxy 23 8.3.1 For HTTP: 23 8.3.2 For HTTPS: 23 Copyright 2013 Kony, Inc. All rights reserved. Page 4 of 23
1. Introduction Kony Messaging Services (KMS) provides generic push notifications service that allows you to send push notifications to mobile devices running different platforms (for example iphone, Android, BlackBerry, and Windows.) Enterprises can use KMS in order to send notifications to applications. In general push notifications are alert notifications. They are sent to only those applications which are subscribed to KMS. The subscribed applications may have different set of message audiences. Using the KMS, user can also define the message target. For example, a banking enterprise uses KMS to send promotional offer as notifications to its Retail Banking application. In this case, end-users who have installed the retail banking applications (and also subscribed to retail banking application) on their mobile device receive the promotional offer in the form of push notification. Note: Graphical user interface environment of the KPNS console is also referred as Kony Messaging Services (KMS). But due to technical reasons, only back-end details related to the console still carry KPNS name such as database script names, database names: - ORACLE_KPNSDB_Create.sql - kpnsdb, DB2_KPNSDB_Create.sql - SCHEMA KPNSQA - Database Name (DEFAULT: kpnsdb): kpnsdb This document explains how to install the KMS console. 1.1 Intended Audience This document is intended for engineers or developers who are responsible for installing and configuring KMS. We assume that the reader of this document is familiar with installing applications in a Linux environment. 1.2 Typographical Conventions Following are the typographical conventions used throughout the document: Convention Explanation User input text, system prompts and responses File Path Monospace Commands Program Code File Names Emphasis Italic Names of Books and Documents New Terminology Copyright 2013 Kony, Inc. All rights reserved. Page 5 of 23
Convention Bold URL Note: Important! Windows Menus Buttons Icons Fields Tabs Active link to a URL Explanation Provides helpful hints or additional information Highlights actions or information that might cause problems to systems or data 1.3 Reference Documents 1. Kony Database Setup Guide (Oracle/MySQL/MSSQL) 2. Kony Messaging Services Console User Guide 1.4 Contact Us We welcome your feedback on our documentation. Email us at techpubs@kony.com. For technical questions, suggestions, comments or to report problems on Kony's product line, contact productsupport@kony.com. Copyright 2013 Kony, Inc. All rights reserved. Page 6 of 23
2. Prerequisites The following sections provide you the information to understand the hardware and software required to install KMS.. 2.1 Software Requirements For software system requirements, click here Note: Database (Metrics / KMS DB / KPNSDB) * Database is shared across instances. To configure Oracle, user should have DBA credentials for Oracle, and Service ID for KMS. 2.2 Hardware Requirements Component Processor Memory Internal Storage Network Operating System Requirement Dual Core Processor 8 GB 150 GB 100 Mbps Ethernet Interface Card Linux-CentOS 5.4 64 Bit 2.3 Creating the Installation User for Linux To create a new user, follow these steps: Note: For security and administrative reasons, install and run KMS Installer as non-root user. # adduser core # passwd core Copyright 2013 Kony, Inc. All rights reserved. Page 7 of 23
3. Corporate Firewall Settings The following firewall settings need to be configured for successful KMS installation. Source Destination Ports Protocol Direction Action Description KMS Server KMS Server KMS Server Internal Corporate WiFi router for Mobile Devices Internal Corporate WiFi router for Mobile Devices Internal Corporate WiFi router for Mobile Devices ehcache internode communication android.apis.google.com, android.googleapis.com gateway.push.apple.com, gateway.sandbox.push.apple.com feedback.push.apple.com, feedback.sandbox.push.apple.co m gateway.push.apple.com, feedback.push.apple.com, gateway.sandbox.push.apple.co m, feedback.sandbox.push.apple.co m ax.init.itunes.apple.com, ocsp.apple.com android.apis.google.com, android.googleapis.com 443 TCP Both Allow 2195 TCP Both Allow 2196 TCP Both Allow 5223 TCP Both Allow 80, 443 TCP Both Allow 443 TCP Both Allow between all KMS server nodes 40001 TCP Both Allow Allow the KMS Server to access Google's C2DM service Allow the KMS Server to access Apple's APNs service Allow the KMS server to access Apple's APNs service Apple devices will connect to APNs servers through this port. Apple devices will connect to public Apple OCSP and itunes service through this port. Android devices will connect to GCM through this port. For distributed caching Copyright 2013 Kony, Inc. All rights reserved. Page 8 of 23
APNS works only with SOCKS proxy type because of the current technical limitation from Apple to communicate the below push notification ports when a proxy server is in place between KMS server and the firewall. TCP port 2195 (used to send notifications to the APNs) TCP port 2196 (used by the APNs feedback service) Alternatively as a work around, to communicate with the above ports, the system on which the KMS server is installed should bypass the proxies and communicate with the firewall directly. Copyright 2013 Kony, Inc. All rights reserved. Page 9 of 23
4. Pre-installation Tasks Before you begin the installation of KMS Installer, you need to perform the following pre-installation tasks to successfully run the installer. 1. Install JDK 1.7 or higher version 4.1 Install JDK 1.7 or Higher Version Before starting KMS installation, download and install Oracle/Sun JDK1.7.0_45 or higher for Linux. The Oracle/Sun JDK for Linux can be downloaded from JDK web page after accepting the Oracle Binary Code License Agreement for Java SE. 4.2 Install Java Environment and Configure JAVA_HOME Perform the following steps to install Java environment: 1. Log in as root user and execute the following commands: # mkdir -p /usr/java # cd <Files_Location> # cp <Files_Location>/jdk-7u45-linux-x64.bin/usr/java # cd /usr/java && chmod a+x *.bin #./jdk-7u45-linux-x64.bin 2. Set the below Java path in.bash_profile or.bashrc files for core and root users. $ vi /home/core/.bash_profile Set JAVA path in file.bash_profile or.bashrc in /User Home directory by appending in it the following lines: export JAVA_HOME=/usr/java/jdk1.7.0_45 export PATH=$JAVA_HOME/bin:$PATH export PATH=$PATH:/usr/sfw/lib/gcc:/usr/sfw/bin 3. Check the Java version installed on your machine using the following command: $ su - core $ java version The following information is displayed: java version "1.7.0_45" Java(TM) SE Runtime Environment (build 1.7.0_45-b10) Java HotSpot(TM) 64-Bit Server VM (build 20.10-b01, mixed mode) Note: If your output does not match the above output, ensure to update the Java Home in.bash_ profile. Kony provides you with an installer to install the KMS. Note: The KMS_installer file includes installers for Tomcat and Jboss. Copyright 2013 Kony, Inc. All rights reserved. Page 10 of 23
Download the KMS Installer from the developer portal by using your developer portal credentials in a zip format, for example KMS-Installer-linux-<version>.GA.zip http://developer.kony.com/konyreleases After downloading the zip file, extract it to get the bin file, for example: KMS_installer- <version>.ga.bin Copyright 2013 Kony, Inc. All rights reserved. Page 11 of 23
5. KMS Files Kony provides the following files for KMS: kpns.war- Application war file that is deployed on the application server. kpns-resources.tar - An extracted kpns-resources.tar archive contains the following files: o o o o jboss - This folder contains the datasource and JMS XML configurations. schema - This folder contains the XML schema definitions for Subscription and Messaging. Database scripts - This folder contains the database scripts for creating and dropping the schema. The scripts for KPNS are available at: http://developer.kony.com/konydbscripts configresource.xml - An XML file containing the configuration properties. o database.properties - o pns-ehcache.xml - o kpns-log4j.properties - This file is used to control the application logging. Copy configresource.xml, database.properties, pns-ehcache.xml, and kpnslog4j.properties to /data/kpns-config folder. Important! For the USERMGMT and KPNSDB the jdbc configurations for the schemas are done at the application server level. For the QUARTZALONE schema the jdbc configurations are to be done in the applicationcontext.xml file. Copyright 2013 Kony, Inc. All rights reserved. Page 12 of 23
6. Installing KMS on Linux Note: If user has to install KMS on a different partition other than user home directory, please ensure read/write execute permissions. This section of the document provides you with the instructions for installing and configuring the KMS Console. Important! Ensure that you have the required hardware and access to the supporting software as mentioned in the Prerequisites section and performed the steps as mentioned in the Pre-installation Tasks section. Note: To install KMS, ensure that you have installed JDK 1.6 64 bit or above on your machine. You must have administrative rights on your computer to install KMS. You have created a user to install the KMS into it. The <Install Location>Logs directory contains the log files documenting each invocation of the installer or uninstaller. Provide these log files to Kony when reporting an issue to help expedite problem identification. 6.1 Installation Procedure To install the KMS console using the installer, follow these steps: 1. Switch to the user that you created by executing the following command: # su - username 2. Press Enter. You will be prompted to enter the password. 3. Enter the password and press Enter. 4. Unzip the downloaded zip file and navigate to the folder KMS_Installer_Linux 5. Start the.bin file by executing the following command: [core@localhost kmsinstller]$./kms_installer-<version>.ga.bin Preparing to install... Extracting the installation resources from the installer archive... Configuring the installer for this system's environment... Launching installer... = KMS (created with InstallAnywhere) ------------------------------------------------------------------------- Preparing CONSOLE Mode Installation... Introduction ------------ InstallAnywhere will guide you through the installation of KMS. Copyright 2013 Kony, Inc. All rights reserved. Page 13 of 23
It is strongly recommended that you quit all programs before continuing with this installation. Respond to each prompt to proceed to the next step in the installation. If you want to change something on a previous step, type 'back'. You may cancel this installation at any time by typing 'quit'. PRESS <ENTER> TO CONTINUE: 6. Press Enter. The Choose Install Folder option appears. Type the location of the install folder. ======================================================================= Choose Install Folder --------------------- Where would you like to install? Default Install Folder: /home/core/kms ENTER AN ABSOLUTE PATH, OR PRESS <ENTER> TO ACCEPT THE DEFAULT : Note: By default, the KMS is installs at the home directory of the user. 7. Press Enter. The Server Choice option appears. Type "1" to continue with Tomcat. Server Choice ------------- Please choose an application server of your choice : ->1- Tomcat 2- JBoss ENTER THE NUMBER FOR YOUR CHOICE, OR PRESS <ENTER> TO ACCEPT THE DEFAULT:: 1 8. Press Enter. The Port for Tomcat/Jboss option appears. Type the IP address and HTTP Port details for the application server. Port for Tomcat/Jboss --------------------- Enter the IP Address and HTTP port you want to use for Tomcat NOTE: Port should be in between 1-65535. IP Address (DEFAULT: 127.0.0.1): HTTP Port (DEFAULT: 8080): Copyright 2013 Kony, Inc. All rights reserved. Page 14 of 23
9. Press Enter. The Run DB Scripts option appears. Type "1" to create KPNS related database. Proxy Settings -------------- KMS is installed behind a proxy? 1- True ->2- False ENTER THE NUMBER FOR YOUR CHOICE, OR PRESS <ENTER> TO ACCEPT THE DEFAULT:: Note: If user selects choice as 1, the system displays the console below: ======================================================================= Proxy Port ---------- Please enter the proxy port Proxy Port (DEFAULT: 80): 83 10. Press Enter. The Run DB Scripts option appears. Type "1" to create KMS related database. Run DB Scripts Option --------------------- Do you want to create KMS related Databases? ->1- Yes 2- No ENTER THE NUMBER FOR YOUR CHOICE, OR PRESS <ENTER> TO ACCEPT THE DEFAULT:: 11. Press Enter. The Database Choice option appears. Type one of the options of your choice. Database Choice --------------- Select a Database of your choice : ->1- MySql 2- SQLServer 3- Oracle ENTER THE NUMBER FOR YOUR CHOICE, OR PRESS <ENTER> TO ACCEPT THE DEFAULT:: 1 Important! The Database IP and credentials console is same both for MySQL and MSSQL if you have selected option as either 1 or 2. 12. Press Enter. Based on your database choice, the Database IP and credentials option appears: for MySQL and MSSQL: Copyright 2013 Kony, Inc. All rights reserved. Page 15 of 23
=================================================================== Database IP and credentials --------------------------- Please enter the database server IP Database IP (DEFAULT: localhost): localhost Port (DEFAULT: 3306): 3306 Database Name (DEFAULT: kpnsdb): kpnsdb Username (DEFAULT: admin): dbclient ==================================================================== Enter Password for Database --------------------------- Please Enter the Password: ==================================================================== DB Connection Successful ------------------------ DB Connection Successful!!! PRESS <ENTER> TO ACCEPT THE FOLLOWING (OK): Important! The Database IP and credentials for Oracle differs than that from MySQL and MSSQL if you have selected option as 3. for Oracle: =================================================================== ==== Database IP and credentials --------------------------- Please enter the database server IP Database IP (DEFAULT: localhost): 10.11.12.182 Port (DEFAULT: 1521): Instance Name (DEFAULT: ): Copyright 2013 Kony, Inc. All rights reserved. Page 16 of 23
Service Id (DEFAULT: ): konydb System Username (DEFAULT: admin): kpnsinstaller DB User for KPNS (DEFAULT: ): kpnsdoc ==================================================================== Enter Password for System User ------------------------------ Please Enter the Password ==================================================================== Enter Password for Database User -------------------------------- Please Enter the Password: ==================================================================== DB Connection Successful ------------------------ DB Connection Successful!!! PRESS <ENTER> TO ACCEPT THE FOLLOWING (OK): Important! Ensure that the details provided are correct and database connection is successful. If you do not see "Successful" in the option, you need to provide the database IP and credentials again. Repeat Step 10. 13. Press Enter. If the database for MySQL and MSSQL already exists, the following warning message appears. Select the appropriate option to proceed further. Warning - Database already exists" ----------------------------------- ->1- Go back to provide database details 2- Skip creating database 3- Abort installation Important! In case of Oracle the installer creates the user in the database. If user already exists in case of Oracle, the following warning message appears: Copyright 2013 Kony, Inc. All rights reserved. Page 17 of 23
Warning - User already exists? ------------------------------- ->1- Go back to provide database details 2- Skip creating database 3- Abort installation 14. Press Enter. The HTTP or HTTPS option appears. Type "1" to configure SSL. Important! If you want to configure SSL, you must have SSL certificates. HTTP or HTTPS ------------- Want to configure SSL? ->1- Yes 2- No ENTER THE NUMBER FOR YOUR CHOICE, OR PRESS <ENTER> TO ACCEPT THE DEFAULT:: 1 15. Press Enter. The HTTPS Port option appears. Type the port details for HTTPS. HTTPS Port ---------- HTTPS Port (DEFAULT: 443): 16. Press Enter. The SSL at Tomcat level option appears. Type the certificates and Press Enter. SSL at Tomcat level ------------------- Please provide the following details Path to Keystore File (DEFAULT: ): /media/sf_shared/kpns_test_ installers/konywildnew.jks Type of Keystore (DEFAULT: JKS): Enter Password for keystore file --------------------------------- Please Enter the Password: For example, SSL certificate for Tomcat. 17. The Pre-Installation Summary option appears on the console. Review the features being installed and Copyright 2013 Kony, Inc. All rights reserved. Page 18 of 23
press Enter. Pre-Installation Summary ------------------------ Please Review the Following Before Continuing: Product Name: KMS Install Folder: /home/core/kms Link Folder: /home/core/kms Disk Space Information (for Installation Target): Required: 545,156,503 Bytes Available: 39,379,271,680 Bytes PRESS <ENTER> TO CONTINUE: 18. The Ready to Install option appears. Press Enter to continue the installer. Ready To Install ---------------- InstallAnywhere is now ready to install KMS onto your system at the following location: /home/core/kms PRESS <ENTER> TO INSTALL: 19. The Installation progress appears on the console. Installing... ------------- [================= ================= ================= =================] [----------------- ----------------- ----------------- -----------------] 20. Once the installation is completed, press Enter to exit from the installer. Installation Complete --------------------- Congratulations. KMS has been successfully installed to: Copyright 2013 Kony, Inc. All rights reserved. Page 19 of 23
/home/core/kms PRESS <ENTER> TO EXIT THE INSTALLER: Copyright 2013 Kony, Inc. All rights reserved. Page 20 of 23
7. Post Installation Tasks After you have installed the KMS, complete the post-installation tasks to configure your server as required. Few steps have to be performed to verify the database successful installation and provide access permissions on some tables. Note: By default configresource.xml file contains default encoding as UTF-8 that supports other than Arabic and Chinese. In addition to the above, if KMS need to support Arabic and Chinese, configure default encoding as UTF-16 in the configresource.xml file in the../kms/kpns-resources location. Note: Follow the below sections only if u have not started the KMS as a service. 7.1 Start KMS Server - Tomcat To launch KMS server, follow these steps: Note: Tomcat logs are stored in <drive>:/kms/tomcat/instance*/logs folder. 1. Navigate to the installdir/tomcat/instance1/bin location. 2. Execute the following command:./startup.sh Once the server is ready, now you can log in to KMS by providing details in browser window. 7.2 Start KMS Server - JBoss 1. Navigate to the installdirectory/jboss/bin 2. Run the command below./standalone.sh 3. You can check the JBoss logs in the installdirectory/jboss/standalone/log. 4. You can also check KMS logs in the installdirectory/logs. Copyright 2013 Kony, Inc. All rights reserved. Page 21 of 23
8. Troubleshooting This section lists the troubleshooting tips to resolve problems that you may encounter during installation. The error messages are stored in log files. 8.1 Error Message Command.run(): Cannot run program "/tmp/640545.tmp/executescripttmp0": java.io.ioexception: error=13, Permission denied XMLScriptWriter: No Installation Objects were skipped Command.run(): Cannot run program "/tmp/640545.tmp/executescripttmp0": java.io.ioexception: error=13, Permission denied Retrying Installables deferred in pass 0 Cause In operating system "/tmp" directory is secured and mounted with "nodev", "nosuid", and "noexec" permissions installer fails to execute the scripts from this location. In enterprise environment this could be a known issue. Solution You can configure the extracts of the installer to a directory where you have read, write and execute permissions. Run the below command before installation. export IATEMPDIR=<absolute path of a temporary directory> 8.2 Error Message SQL exception while starting KMS Server for Jboss + Oracle combination ERROR [org.jboss.kernel.plugins.dependency.abstractkernelcontroller] (main) Error installing to Start: name=persistence.unit:unitname=#kms state=create javax.persistence.persistenceexception: [PersistenceUnit: kms] Unable to build EntityManagerFactory at org.hibernate.ejb.ejb3configuration.buildentitymanagerfactory (Ejb3Configuration.java:677) at org.hibernate.ejb.hibernatepersistence.createcontainerentitymanagerfactory (HibernatePersistence.java:132) at org.jboss.jpa.deployment.persistenceunitdeployment.start (PersistenceUnitDeployment.java:301) at sun.reflect.nativemethodaccessorimpl.invoke0(native Method) Cause Missing -D parameter for Jboss + Oracle combination Solution Copyright 2013 Kony, Inc. All rights reserved. Page 22 of 23
If you are using KMS Installer 5.6.0GA version, to install Jboss + Oracle combination, please add the below mentioned -D parameter in run.sh file before starting the KMS server: Open run.sh file from location USERINSTALLDIR/jboss/bin and add D param -Dhibernate.dialect=org.hibernate.dialect.Oracle10gDialect. 8.3 JBoss Server Behind Proxy Note: This is applicable only for 5.6.2 GA installer. If you use JBoss server behind proxy, you need to add Proxy port in installeddir/jboss/standalone/configuration/standalone.xml file in connector segment as mentioned below: 8.3.1 For HTTP: <connector name="http" protocol="http/1.1" scheme="http" socketbinding="http" proxy-port="<port number>"/> 8.3.2 For HTTPS: <connector name="http" protocol="http/1.1" scheme="http" socketbinding="http" proxy-port="<port number>"/> <connector name="https" protocol="http/1.1" scheme="https" socketbinding="https" secure="true"><ssl name="https" password="<appserver_ KEYSTORE_PASS>" certificate-key-file="<appserver_keystore_file>" proxy-port="<port number>"/> </connector> Copyright 2013 Kony, Inc. All rights reserved. Page 23 of 23