IBM i2 Intelligence Analysis Platform Windows Deployment Guide

Transcription

1 IBM i2 Intelligence Analysis Platform Windows Deployment Guide Version 3 Release 0 SC

2 Note Before using this information and the product it supports, read the information in Notices on page 69. This edition applies to version 3, release 0, modification 9 of IBM i2 Intelligence Analysis Platform (product number 5725-G22) and to all subsequent releases and modifications until otherwise indicated in new editions. Copyright IBM Corporation 2012, US Government Users Restricted Rights Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp.

3 Contents Chapter 1. About this guide Chapter 2. Contacting IBM support... 3 Chapter 3. Deployment planning Physical model Data model Intelligence Analysis Platform schemas Security model Dimensions and values Permissions and tags Intelligence Analysis Platform principal provider 9 Data acquisition Chapter 4. The IBM i2 Intelligence Analysis Platform deployment toolkit structure Chapter 5. Deployment sequence Chapter 6. Configuring the environment and the applications Software prerequisites Configuring environment settings Setting the write-side environment properties.. 20 Setting the read-side environment properties.. 23 Providing a JDBC driver Providing the JDBC driver for DB Providing the JDBC driver for SQL Server Providing the JDBC driver for Oracle Providing the derby.jar file Specifying the deployment structure Specifying credentials Configuring application settings Specifying a security schema Setting default permissions for items Specifying the platform schema and the charting scheme Setting global application properties Chapter 7. Deploying the Intelligence Analysis Platform Chapter 8. Setting up Application Server Security Creating WebSphere federated repositories Creating WebSphere groups Adding and categorizing your users Chapter 9. Restarting WebSphere Application Server Chapter 10. Opening the Intelligence Portal Chapter 11. Monitor your deployment 43 Logged information Chapter 12. Connecting Analyst's Notebook Premium to the Intelligence Analysis Platform Chapter 13. Backup strategy Core components Additional components Backing up your system while it is offline Appendix A. Security schemas Security schema definitions Security dimension definitions Security tag group definitions Security tag definitions Creating a security schema Appendix B. The topology Intelligence Analysis Platform data sources Databases JMS server Applications Appendix C. Indexing Specifying the index language Creating a custom alternative term index Appendix D. Setting up a localized deployment Specifying the index language Enabling bi-directional text support Notices Trademarks Copyright IBM Corp. 2012, 2015 iii

4 iv Windows Deployment Guide

5 Chapter 1. About this guide This guide describes how to deploy the IBM i2 Intelligence Analysis Platform into an environment that contains two physical servers. The instructions use the Intelligence Analysis Platform deployment toolkit, which produces a set of deployment artifacts that make both the initial process and subsequent upgrades easier to manage. The instructions assume that you have access to distributions of the following software, as well as Intelligence Analysis Platform: v IBM WebSphere Application Server Full profile 8.0 Fix Pack 9, Fix Pack 4, or IBM WebSphere Application Server Liberty profile Fix Pack 4 v IBM Java 7.1 SDK , if you are using WebSphere Application Server Liberty profile Note: WebSphere Application Server Full profile deployments use the WebSphere Java 6 (J9 2.6). v IBM WebSphere MQ 7.5 Fix Pack 4 v One of the supported database management systems: IBM DB2 Enterprise or Workgroup Server 9.7 Fix Pack 5, 10.1, or 10.5 Fix Pack 5 Microsoft SQL Server 2008, 2012, or 2014 Oracle Database 11g Standard Edition Release 2 The deployment process also requires some tools and utilities that you can download from the Internet when they are necessary. Attention: While IBM takes reasonable steps to verify the suitability of Intelligence Analysis Platform for Internet deployment, this guide covers aspects of a deployment only at the application level. It does not address lower-level issues such as guarding networks against penetration, firewall configurations to avoid DoS or DDoS attacks, load balancing and the like. In deploying Intelligence Analysis Platform, follow industry-standard practices and recommendations for protection of your systems. IBM accepts no liability for the consequences of such attacks on your systems. Intended audience This guide is intended for readers who are familiar with deploying web services into existing infrastructures that use an application server and one of the supported databases. Furthermore, the guide is aimed specifically at enabling deployments of the Intelligence Analysis Platform on servers that run Microsoft Windows. Copyright IBM Corp. 2012,

6 2 Windows Deployment Guide

7 Chapter 2. Contacting IBM support IBM Support provides assistance with product defects, answers FAQs, and helps users to resolve problems with the product. About this task After trying to find your answer or solution by using other self-help options such as technotes, you can contact IBM Support. Before contacting IBM Support, your company or organization must have an active IBM software subscription and support contract, and you must be authorized to submit problems to IBM. For information about the types of available support, see the Support portfolio topic in the Software Support Handbook. Procedure To contact IBM Support about a problem: 1. Define the problem, gather background information, and determine the severity of the problem. For more information, see the Getting IBM Support topic in the Software Support Handbook. 2. Gather diagnostic information. 3. Submit the problem to IBM Support in one of the following ways: a. Online through the IBM Support Portal at support. You can open, update, and view all of your service requests from the Service Request portlet on the Service Request page. b. By phone: For the phone number to call in your region, see the Directory of worldwide contacts web page at Results If the problem that you submit is for a software defect or for missing or inaccurate documentation, IBM Support creates an Authorized Program Analysis Report (APAR). The APAR describes the problem in detail. Whenever possible, IBM Support provides a workaround that you can implement until the APAR is resolved and a fix is delivered. IBM publishes resolved APARs on the IBM Support website daily, so that other users who experience the same problem can benefit from the same resolution. Copyright IBM Corp. 2012,

8 4 Windows Deployment Guide

9 Chapter 3. Deployment planning Physical model Planning a deployment of the Intelligence Analysis Platform ensures that the system matches the needs of your organization. By understanding the organizational requirements and tailoring the solution before you begin, you can avoid multiple deployment iterations. Before you start a deployment, take time to ensure that you understand the following aspects of the proposed system: v v v v The physical architecture into which the Intelligence Analysis Platform is to be deployed The structure of the data to be analyzed, both existing and planned The security infrastructure into which the Intelligence Analysis Platform must integrate The locations of any external data sources that need to be accessed The IBM i2 Intelligence Analysis Platform is designed for deployment across at least two physical servers, and for extension across several more. The platform also supports expansion through the addition of new servers and services to an existing deployment. The Intelligence Analysis Platform demonstrates command and query responsibility segregation (CQRS). Services in the platform can write or read information, but never both. The logical architecture of the platform defines a write side and a read side: v v The write side contains services and infrastructure that clients use to create, edit, and delete information. It also hosts the Intelligence Portal, which is the web-based interface through which users interact with the platform. The read side of an Intelligence Analysis Platform deployment contains services and infrastructure that enables clients to visualize and analyze information. When you deploy the Intelligence Analysis Platform by following the instructions in this guide, the physical architecture matches this diagram: Copyright IBM Corp. 2012,

10 A standard deployment of the platform has the following physical components: v A write-side and a read-side server, with instances of either IBM WebSphere Application Server Full profile or IBM WebSphere Application Server Liberty profile and a matching database management system on both. v On the write-side server, an HTTP server that acts as a proxy server for client requests. v In the instance of the application server on the write side, an application that contains the standard Intelligence Analysis Platform write-side services. v In the instance of the application server on the read side, an application that contains the standard Intelligence Analysis Platform read-side services. Before you begin deployment, you need to know the types and network addresses of the servers that are intended to host the Intelligence Analysis Platform. This information is required on several occasions during the deployment procedure. Data model The Intelligence Analysis Platform models data in terms of entities, links, and properties. When you deploy the platform, you must decide how your information can be represented by entities, links, and properties of different types. Entities, links, and properties (ELP) are the basic concepts in the Intelligence Analysis Platform data model. Entities and links can be named collectively as items. v An entity represents a real-world object, such as a Person or a Car. v v A link associates two entities with each other. For example, a Person entity might be associated with a Car entity through an Owns link. A property stores a value that characterizes an entity or a link. For example, a Person entity might have properties that record its given name, surname, date of birth, and hair color. 6 Windows Deployment Guide

11 Starting from these basic concepts, the Intelligence Analysis Platform data model is designed to support rich analytical abilities. When you deploy the platform, you specify a schema that expresses your data in ELP terms. A well-designed schema allows users to request effective searches, view properly aligned results, and perform valuable results analysis. Intelligence Analysis Platform schemas The Intelligence Analysis Platform schema describes the items that users interact with when they use your deployment. The schema also defines the relationships that can exist between items of different types, and therefore the structure of the data in the Analysis Repository. Note: "Analysis Repository" is an umbrella term for the databases that make up the principal data store in a deployment of the Intelligence Analysis Platform. All deployments of the platform have an Analysis Repository; some deployments interact with other data stores as well. Your deployment of the Intelligence Analysis Platform must have a schema that is appropriate for the information in your domain. The schema fulfills the following roles: v v v It describes the data that platform users interact with in terms of entity types, link types, property types, and property group types. It defines what types of links are allowed between entities of particular types, aiding analysis and data quality. It specifies what entities and links look like when they are visualized as results on charts. Note: The last role is the responsibility of a charting scheme, which is a separate document that the schema refers to. Schemas and charting schemes have a one-to-one relationship. An Intelligence Analysis Platform schema is an XML representation of the item types that you identify in your data. Every deployment requires a schema, and there are three ways to choose or create one. v v v The Intelligence Analysis Platform deployment toolkit includes example schemas that target particular domains: commercial insurance, law enforcement, and military intelligence. If one of the supplied schemas matches your requirements, you can use it without modification. Alternatively, one of the supplied schemas might contain some of the entity and link types that you need. If you can meet your requirements by expanding or modifying the existing types, then you can edit the schema to make it fit for purpose. If none of the supplied schemas is appropriate, then you can create your own schema that precisely matches the data in your organization. You can view, edit, and create Intelligence Analysis Platform schemas with Analysis Repository Schema Designer, which is a tool that IBM provides with the platform. Analysis Repository Schema Designer displays the structure of your schema, and ensures that the XML schema files that you create are compatible with the platform. Chapter 3. Deployment planning 7

12 Security model The IBM i2 Intelligence Analysis Platform security model enables the platform to determine the rights of individual users to manipulate the items that they are working with. When you deploy the platform, you provide a security schema that categorizes users, and define how those categories affect their access to information. The Intelligence Analysis Platform security model bases its behavior on the interaction between security dimensions of users and the security permissions of items. Dimensions and values A security dimension is a way to distinguish different kinds of Intelligence Analysis Platform user, with the aim of determining what rights they receive. The security dimensions for any deployment of the platform are defined in the security schema for that deployment. For a particular deployment of the Intelligence Analysis Platform, there might be several different ways of distinguishing users, resulting in multiple dimensions. For example: v v Users might be distinguished according to their clearance to see items with different security classifications. Users might be distinguished according to their job titles. Each security dimension contains a set of values that classify the users within that dimension. To continue the example, the different dimensions might have values as follows: Dimension name Security classification Job title Dimension values Top Secret, Secret, Confidential, Restricted Clerk, Analyst, Manager In some dimensions (such as security classification), the values form a sequence from which each user takes a single value. In such cases, the values are considered to be levels, where each value encompasses all the values below it. In dimensions where the values do not form a sequence, users can take one or more values. Every user of an Intelligence Analysis Platform deployment must be assigned at least one value for each of the dimensions in that deployment. 8 Windows Deployment Guide

13 Permissions and tags Every item in the Intelligence Analysis Platform has a set of security permissions that associate the dimension values of a user with their ability to view or edit that item. There are two types of security permissions: v A security access permission affects whether a user with a particular dimension value can see an item at all; and if they can, whether they can also edit it. v A security grant permission affects whether a user can change the security permissions of an item. For example, the security permissions for an item might dictate that a user with a "Top Secret" dimension value can view it, but a user with a "Restricted" value cannot. Similarly, the permissions might specify that only users with the "Manager" value are able to change which other users can edit an item. There are two ways to set the security permissions for an item, depending on the requirements of the deployment: v v Specify each security permission separately for each item. In a deployment that uses this approach, the security schema defines only security dimensions, and users see the names and values of those dimensions in the Intelligence Portal. Use security tags as a way to specify several related security permissions at the same time. In a deployment that uses this approach, the security schema defines security dimensions and security tags, and users see the names of the tags in the Intelligence Portal. Because of these different approaches, every item in the Intelligence Analysis Platform has either two lists of permissions (access and grant), or one list of tags. The effect of "tagging" an item is to set the permissions for several kinds of user with a single action. Intelligence Analysis Platform principal provider In a deployment of the Intelligence Analysis Platform, the security schema defines the available security dimensions, and all the values that users can have in those dimensions. All deployments have a custom security schema that reflects their particular requirements. To complete the security model, the Intelligence Analysis Platform also needs a mechanism that can associate dimension values from the security schema with particular users. This task is the responsibility of a principal provider, which you specify during deployment. The Intelligence Analysis Platform deployment toolkit includes a principal provider that interacts with the user and group management function in WebSphere Application Server Full profile and WebSphere Application Server Liberty profile. The groups that users are in become the dimension values of those users. Chapter 3. Deployment planning 9

14 10 Windows Deployment Guide To use the supplied principal provider, the dimension values in your security schema must match the names of user groups in the application server. The deployment toolkit contains an example security schema that illustrates the approach, including some security tag definitions that use the dimension values. However, a real deployment always requires you to create your own security schema.

15 Data acquisition The Intelligence Analysis Platform is not limited to operating on data that users enter through the Intelligence Portal. The platform supports several mechanisms for interacting with data that comes from outside the system, some of which have implications for deployment. Depending on the type, the format, and the intended use of external data, the Intelligence Analysis Platform can acquire it in different ways. You can arrange for data to be imported directly, or you can configure the platform to connect to external systems and retrieve data when it is requested. Acquisition type Description Suitable data File import Use the Analyst's Notebook Premium importer or the Analyst's Notebook Premium chart item uploader to add smaller amounts of data from text files, spreadsheets, or charts to the Analysis Repository. A record of the telephone calls between two individuals that are being investigated. Data load direct Data load ELP stage Data access on-demand Use a custom application to add a larger amount of data to the Analysis Repository in a one-off operation. This method is appropriate for data that is not going to be updated in the original source. Use a custom application to add data to a secondary repository that is hosted on a separate server. This method is appropriate for data that is not subject to rapid changes, but is not yet static. Use a custom Intelligence Analysis Platform service to connect directly to data that is still being updated regularly in its original source. Custom services can be deployed alongside a standard platform deployment. The records of a closed investigation. The records of an active investigation that is nearing prosecution. The records of an active investigation. When a data acquisition solution requires a custom configuration of the Intelligence Analysis Platform, you can deploy it at the same time as the platform or modify an existing deployment. For more information about data acquisition solutions, see the IBM i2 Intelligence Analysis Platform Data Acquisition Developer Guide. Chapter 3. Deployment planning 11

16 12 Windows Deployment Guide

17 Chapter 4. The IBM i2 Intelligence Analysis Platform deployment toolkit structure The Intelligence Analysis Platform deployment toolkit contains scripts and components that you need to deploy and maintain the Intelligence Analysis Platform. The deployment toolkit contains two directories that you interact with: configuration The configuration directory contains the templates and files that you must complete to allow the deployment scripts to identify and connect to the core components of your deployment. Note: You can add more files to this location to further configure a deployment. scripts The scripts directory contains the main deployment and upgrade scripts that you use to create and deploy the application. In summary, the configuration directory contains files that you must update with information specific to your deployment. When you have provided this information, you can use the deployment and upgrade scripts to administer your IBM i2 Intelligence Analysis Platform deployment. Copyright IBM Corp. 2012,

18 14 Windows Deployment Guide

19 Chapter 5. Deployment sequence The IBM i2 Intelligence Analysis Platform deployment toolkit enables several of the actions in a sequence that results in a production-ready deployment of the platform. The artifacts that you create when you follow this sequence make it easier to upgrade and administer the deployed platform. The following list is an outline of the Intelligence Analysis Platform deployment sequence, from the installation of prerequisite software to the connection of the first user: 1. Install the prerequisite software on the write-side and read-side servers. 2. Configure the server environments into which the platform is to be deployed. 3. Specify the topology of the deployment. 4. Provide the user names and passwords that the deployment process requires. 5. Create an Intelligence Analysis Platform security schema. 6. Set the default permissions for new items. 7. Select or create an Intelligence Analysis Platform schema and charting scheme. 8. Configure the Intelligence Analysis Platform applications to use your deployment artifacts. 9. Run the scripts that deploy and start the servers. 10. Configure the application server security. 11. Start the applications. 12. Connect to the Intelligence Portal as a user, and test it. Copyright IBM Corp. 2012,

20 16 Windows Deployment Guide

21 Chapter 6. Configuring the environment and the applications Software prerequisites The Intelligence Analysis Platform deployment toolkit automates many of the tasks that are typically involved in installing and configuring web applications. To perform these tasks, the toolkit requires information about the environment into which you are deploying the Intelligence Analysis Platform, and settings for the write and read applications of the platform. Before you can take advantage of the automation in the deployment toolkit, you must install the prerequisite software, and provide values for properties in a handful of configuration files. The IBM i2 Intelligence Analysis Platform has a range of prerequisite software that you must install before you can deploy the platform itself. On the write-side server, the prerequisites are: v The Intelligence Analysis Platform distribution, installed according to the instructions in the IBM i2 Intelligence Analysis Platform Release Notes. v One of the supported application servers: IBM WebSphere Application Server Full profile 8.0 Fix Pack 9 IBM WebSphere Application Server Full profile Fix Pack 4 IBM WebSphere Application Server Liberty profile Fix Pack 4 v IBM Java 7.1 SDK , if you are using WebSphere Application Server Liberty profile Note: WebSphere Application Server Full profile deployments use the WebSphere Java 6 (J9 2.6). v Python 2.7 v IBM WebSphere MQ 7.5 Fix Pack 4 v One of the supported database management systems: IBM DB2 Enterprise or Workgroup Server 9.7 Fix Pack 10, 10.1, or 10.5 Fix Pack 5 Microsoft SQL Server 2008 Service Pack 4, 2012, or 2014 Oracle Database 11g Standard Edition Release 2 (Patch ) Note: It is critical to update any instances of DB2 9.7 to at least Fix Pack 5. To use the instructions as they are written, you must also add the directory that contains python.exe to your path. On the read-side server, the prerequisites are: v One of the supported application servers: IBM WebSphere Application Server Full profile 8.0 Fix Pack 9 IBM WebSphere Application Server Full profile Fix Pack 4 IBM WebSphere Application Server Liberty profile Fix Pack 4 v IBM Java 7.1 SDK , if you are using WebSphere Application Server Liberty profile Copyright IBM Corp. 2012,

22 Note: WebSphere Application Server Full profile deployments use the WebSphere Java 6 (J9 2.6). v Python 2.7 v One of the supported database management systems: IBM DB2 Enterprise or Workgroup 9.7 Fix Pack 10, or IBM DB2 10.1, or 10.5 Fix Pack 5 Microsoft SQL Server 2008 Service Pack 4, 2012, or 2014 Oracle Database 11g Standard Edition Release 2 (Patch ) In addition, your environment must contain an HTTP server that supports a reverse proxy. Clients must be able to connect to the web server and use Intelligence Analysis Platform services without being aware of the underlying architecture. One example of suitable software for setting up a reverse proxy is IBM HTTP Server 8.0, working together with the web server plug-ins for IBM WebSphere Application Server Full profile 8.0. Installing prerequisite software When you install the prerequisite software, you must do so according to the following specifications. Unless stated, the prerequisite software must be installed and configured on both servers in the same way. IBM WebSphere Application Server Full profile 8.0 Fix Pack 9, Fix Pack 4, or IBM WebSphere Application Server Liberty profile Fix Pack 4 WebSphere Application Server can have all of its default settings, except that you must change the installation location from the default setting (C:\Program Files\IBM). Choose a directory that reduces the path length and avoids spaces (for example, C:\IBM). For a deployment that uses WebSphere Application Server Liberty profile, you must also install the Extended Programming Models asset to enable web services. See IBM Knowledge Center for further information. It is not necessary to set up a WebSphere profile at this stage. The Intelligence Analysis Platform deployment toolkit creates profiles automatically. IBM WebSphere MQ 7.5 Fix Pack 4 Note: IBM WebSphere MQ 7.5 is not required on read-side servers. Install WebSphere MQ by using a custom setup. You must change the locations for installation, data files, and log files from the default setting (C:\Program Files\IBM). Choose a directory that reduces the path length and avoids spaces (for example, C:\IBM\WebSphereMQ). 18 Windows Deployment Guide

23 Install WebSphere MQ with the following features: v Server v WebSphere MQ Explorer v Windows Client v Java and.net Messaging and Web Services v Development Toolkit WebSphere MQ is now installed and ready to be configured for use in the Intelligence Analysis Platform. Add your user account to the mqm group, and then restart the computer. IBM DB2 Enterprise or Workgroup Server Edition 9.7 Fix Pack 10, 10.1, or 10.5 Fix Pack 5 If you choose to use the DB2 database management system, DB2 can have all of its default settings, except that it is not necessary to set up a response file. You can also turn off DB2 notifications. During setup, DB2 creates a Windows user account for itself (db2admin), and two Windows groups (DB2ADMNS, DB2USERS). To work successfully with DB2, ensure that your Windows user account is a member of the DB2ADMNS Windows group. Microsoft SQL Server 2008 Service Pack 4, 2012, or 2014 If you choose to use the Microsoft SQL Server database management system, Microsoft SQL Server can have all of its default settings, except that you must enable SQL Server Authentication. Oracle Database 11g Standard Edition Release 2 (Patch ) If you choose to use the Oracle database management system, Oracle can have all of its default settings, except that you must set the character set to Unicode (AL32UT8). As Oracle database creation is not currently handled by the deployment scripts, you must create each database manually, and each database must be configured to use a unique user. To work with the examples given, you must create three databases as follows: Database id Database host Database type doc1 Write-side DocumentStore write1 Write-side WriteStore item1 Read-side ItenRetrievalStore Note: Regardless of the database management system, the user that you use to run the deployment scripts must have permission to create and modify the databases. Finally, in addition to installing the prerequisite software, you must ensure that Microsoft Internet Information Server is either inactive or not present on the write-side server. HTTP server and reverse proxy Because the Intelligence Analysis Platform read-side and write-side servers are physically separate, a working deployment requires a reverse proxy server that routes client requests to the appropriate destination. Chapter 6. Configuring the environment and the applications 19

24 Your environment might already contain a server that fulfills (or can be made to fulfill) this role. If it does not, the deployment toolkit can automatically configure an IBM HTTP Server on the write-side server to act as a reverse proxy. To support this approach, you must install the following software: v IBM HTTP Server (on the write side) v Web server plug-ins for IBM WebSphere Application Server Full profile (on the write side and the read side) If you use IBM HTTP Server, then you must install both pieces of software similarly to WebSphere. That is, remove Program Files from the default installation paths, and leave all the other options with their default settings. Note: Ensure that the ports used by WebSphere Application Server Full profile and your database do not conflict with other applications, and that any firewall is configured to allow communication through them. Configuring environment settings To use the automation in the deployment toolkit, you must provide details about how you set up the prerequisite software, and the computers where you installed it. This information allows the toolkit to connect to and modify your components as part of the deployment process. About this task The deployment toolkit expects to find information for and about the environment that you are installing into in the IAP-Deployment-Toolkit\configuration\ environment directory. However, the configuration directory does not exist in the toolkit by default. Instead, a new installation of the deployment toolkit contains a directory with the name configuration-example. The configuration-example directory contains further directories that store settings files for each server type, and a common directory that stores files that are used across the system. You must make a copy of configuration-example to use as the working configuration directory. Procedure 1. Navigate to the IAP-Deployment-Toolkit directory. 2. Make a copy of the configuration-example directory in the same location, and name it configuration. Results The configuration directory is your working area for the rest of the deployment procedure. The configuration-example directory remains as a store for clean configuration files that you can revert to. Setting the write-side environment properties The scripts in the deployment toolkit that deploy the Intelligence Analysis Platform require information about your application server, your database, and some other system components. For the write side, you must add settings that describe your environment to the environment.properties file in the configuration\ environment\write directory. 20 Windows Deployment Guide

25 About this task The environment.properties file contains a range of settings that you must configure before you can deploy the Intelligence Analysis Platform. Note: Ensure that all file paths use forward slashes (/). db.installation.dir.db2 The installation path for DB2 on the write-side server, which is necessary for running the DB2 SQL executor. For example, C:/Program Files/IBM/SQLLIB. This setting can be left blank for a deployment that uses SQL Server or Oracle. db.database.location.dir.db2 The path to the directory at the root of DB2 database file storage. For example, C:. This setting can be left blank for a deployment that uses SQL Server or Oracle. was.home.dir The path to the WebSphere Application Server Full profile directory on the write-side server. This property is parsed by Python, so the value must be on a single line. For example, C:/IBM/WebSphere/AppServer. Note: Leave it blank for deployments on WebSphere Application Server Liberty profile. wlp.home.dir The path to the WebSphere Application Server Liberty profile installation directory on this server. For example, C:/IBM/wlp. Note: This setting is only required for deployments on WebSphere Application Server Liberty profile. Leave it blank for deployments on WebSphere Application Server Full profile. java.home.dir The path to an IBM Java JDK installation directory. Complete this setting for a WebSphere Application Server Liberty profile deployment, or leave it blank for a WebSphere Application Server Full profile deployment. For example, C:/IBM/wlp/java. mq.home.dir The path to the home directory for WebSphere MQ. For example, C:/IBM/WebSphereMQ. mq.var.dir The path to the var directory for WebSphere MQ. This path is usually the same as for the home directory. http.server.home.dir The path to the installation directory of IBM HTTP Server. For example, C:/IBM/HTTPServer. This setting is required so that the deployment scripts can configure the HTTP server automatically. http.was.module.dir The path to the WebSphere plug-in for IBM HTTP Server. For example, C:/IBM/WebSphere/Plugins/bin/32bits. Chapter 6. Configuring the environment and the applications 21

26 Note: The path might vary, but you must use the 32-bit version of the plug-in, regardless of the underlying architecture of the operating system. http.server.ssl.enabled The status of SSL mode on the HTTP server. When this setting is true, the http.server.host.name and http.server.keystore.dir properties must also be set. Note: The security implementation that IBM provides with the Intelligence Analysis Platform sends user names and passwords in HTTP headers, in plain text. If you allow access from outside a firewall, strongly consider enabling SSL. http.server.host.name The host name of the HTTP server. This setting is only required if SSL is enabled. It is used to redirect non-secure HTTP requests to a secure channel. Leave this setting blank if SSL is not enabled. http.server.keystore.dir The path to the key database for the HTTP server. This database must be created and populated before you enable SSL. Leave this setting blank if SSL is not enabled. help.port.number The port on the write-side server to which the Intelligence Analysis Platform deployment scripts publish the web help for the Intelligence Portal. For example, Ensure that the port is not already in use. help.content.dir The path to a directory that the Intelligence Analysis Platform deployment scripts create to store the web help files. For example, ${was.home.dir}/webhelp or ${wlp.home.dir}/webhelp. apollo.data The path to an Intelligence Analysis Platform data directory where temporary documents are stored. For example, C:/iap-data. The deployment toolkit creates this directory if it does not exist. Procedure 1. Using a text editor, open the environment.properties file for the write-side server. You can find this file in the following location: IAP-Deployment-Toolkit\ configuration\environment\write. 2. Using the preceding descriptions, populate the property values for the application server, WebSphere MQ, the data directory, and the web help, for your environment. Note: The deployment scripts use these properties for setting up the environment and creating the Intelligence Analysis Platform applications. As such, the values of these properties can overwrite values that are stored in other files. Treat the environment.properties file as the source of truth about your deployment. 3. Optional: If you are using DB2, populate the following property values to identify the installation path and database root: v db.installation.dir.db2 v db.database.location.dir.db2 4. Optional: If you are using IBM HTTP Server, populate the following property values to enable automatic configuration of the reverse proxy: 22 Windows Deployment Guide

27 v http.server.home.dir v http.was.module.dir v http.server.ssl.enabled 5. Optional: If you are using IBM HTTP Server with SSL enabled, also populate the following property values: v http.server.host.name v http.server.keystore.dir 6. Save and close the file. Setting the read-side environment properties The scripts in the deployment toolkit that deploy the Intelligence Analysis Platform require information about your application server, your database, and some other system components. For the read side, you must add settings that describe your environment to the environment.properties file in the configuration\ environment\read directory. About this task The environment.properties file contains a range of settings that you must configure before you can deploy the Intelligence Analysis Platform: db.upgrade.security.schema.file.name The name of the security schema XML file, which must be in the same directory as environment.properties. The file is a copy of the one that is deployed on the write-side server. It is loaded when the application starts after an upgrade. Note: This setting is only required when you are upgrading a deployment. Leave it blank unless an upgrade of a deployment is taking place. db.installation.dir.db2 The installation path for DB2 on the read-side server, which is necessary for running the DB2 SQL executor. For example, C:/Program Files/IBM/SQLLIB. This setting can be left blank for a deployment that uses SQL Server or Oracle. db.database.location.dir.db2 The path to the directory at the root of DB2 database file storage. For example, C:. This setting can be left blank for a deployment that uses SQL Server or Oracle. was.home.dir The path to the WebSphere Application Server Full profile directory on the read-side server. This property is parsed by Python, so the value must be on a single line. For example, C:/IBM/WebSphere/AppServer. Leave it blank for deployments on WebSphere Application Server Liberty profile. wlp.home.dir The path to the WebSphere Application Server Liberty profile installation directory on this server. For example, C:/IBM/wlp. Note: This setting is only required for deployments on WebSphere Application Server Liberty profile. Leave it blank for deployments on Chapter 6. Configuring the environment and the applications 23

28 Providing a JDBC driver WebSphere Application Server Full profile. java.home.dir The path to an IBM Java JDK installation directory. Complete this setting for a WebSphere Application Server Liberty profile deployment, or leave it blank for a WebSphere Application Server Full profile deployment. For example, C:/IBM/wlp/java. apollo.data The path to an Intelligence Analysis Platform data directory where temporary documents are stored. For example, C:/iap-data. The deployment toolkit creates this directory if it does not exist. Procedure 1. Using a text editor, open the environment.properties file for the read-side server. You can find this file in the following location: IAP-Deployment-Toolkit\ configuration\environment\read. 2. Using the preceding descriptions, populate the property values for WebSphere, and the data directory for your environment. 3. Optional: If you are using DB2, populate the following property values to identify the installation path and database root: v db.installation.dir.db2 v db.database.location.dir.db2 4. Save and close the file. The Application Server requires a JDBC driver to enable communication with the databases. If you provide the driver to the deployment toolkit, the toolkit can deploy it to the correct locations on the write-side and read-side servers. About this task Depending on the type of database management system that you have installed, the steps for providing a JDBC driver differ. Select the steps that relate to the database management system that you have installed. If you are using WebSphere Application Server Liberty profile, you must also provide the derby.jar file. For Microsoft SQL Server or Oracle deployments, you must edit the environment-advanced.properties file to reference the correct.jar file. Providing the JDBC driver for DB2 The JDBC driver for DB2 is stored in your DB2 installation directory. You must copy this driver to the deployment toolkit so that it can be deployed correctly. Procedure 1. In the DB2 installation directory, locate IBM\SQLLIB\java\db2jcc4.jar. 2. Copy db2jcc4.jar to the IAP-Deployment-Toolkit\configuration\environment\ common\jdbc-drivers directory. 24 Windows Deployment Guide

29 Providing the JDBC driver for SQL Server The JDBC driver for SQL Server is available online. You must copy this driver to the deployment toolkit, and reference the driver from both copies of environment-advanced.properties. Procedure 1. Download the jtds dist.zip file from jtds/files/jtds/1.2.4/ and extract the contents. 2. Copy jtds jar file to the IAP-Deployment-Toolkit\configuration\ environment\common\jdbc-drivers directory. 3. Using a text editor, open the environment-advanced.properties files for the write-side server and the read-side server. You can find these files in the following locations: v IAP-Deployment-Toolkit\configuration\environment\write v IAP-Deployment-Toolkit\configuration\environment\read 4. In both files, set the jdbc.driver.jar.name property to jtds jar. 5. Save and close the files. Providing the JDBC driver for Oracle The JDBC driver for Oracle is stored in your Oracle installation directory. You must copy this driver to the deployment toolkit, and reference the driver from both copies of environment-advanced.properties. Procedure 1. In the Oracle installation directory, locate Product\11.2.0\dbhome_1\jdbc\lib\ ojdbc6.jar. 2. Copy ojdbc6.jar to the IAP-Deployment-Toolkit\configuration\environment\ common\jdbc-drivers directory. 3. Using a text editor, open the environment-advanced.properties files for the write-side server and the read-side server. You can find these files in the following locations: v IAP-Deployment-Toolkit\configuration\environment\write v IAP-Deployment-Toolkit\configuration\environment\read 4. In both files, set the jdbc.driver.jar.name property to ojdbc6.jar. 5. Save and close the files. Providing the derby.jar file If you are using WebSphere Application Server Liberty profile, you must download the derby.jar file and copy this driver to the deployment toolkit so that it can be deployed correctly. Procedure 1. In a web browser, go to Apache Derby Release. Follow the instructions to download the derby.jar file. 2. Copy the downloaded derby.jar file to the IAP-Deployment-Toolkit\ configuration\environment\common\jdbc-drivers directory. Chapter 6. Configuring the environment and the applications 25

30 Specifying the deployment structure In the deployment toolkit, the topology.xml file contains information about the physical architecture of the Intelligence Analysis Platform. To identify the components of the system that you are deploying, you must add deployment-specific information to the topology.xml file. About this task If you are deploying the platform into a two-server environment, the changes to topology.xml that you need to make are to identify the host names of your servers, and the location to store search index information. In addition, if you have multiple database instances setup, you need to change the database instance-name to the database instance name where the database was created. For example, myinst. Note: To set up deployment with multiple applications or multiple application servers, you must extend the topology.xml file to reflect your architecture. More information on the topology can be found in Appendix B. The topology. Procedure 1. Copy the version of topology.xml that is specific to the database management system you are using from the examples directory into IAP-Deployment- Toolkit\configuration\environment. The topology files can be found in the following location: IAP-Deployment-Toolkit\configuration\examples\topology\ database management system type\topology.xml. 2. Using an XML editor, open IAP-Deployment-Toolkit\configuration\ environment\topology.xml. 3. Populate the host-name attributes of the following elements. Element database jms-server application Attribute values Specify the host names of the servers that are being used to store the databases. In a two-server deployment, the DocumentStore and the WriteStore use the write-side server, and the ItemRetrievalStore uses the read-side server. Specify the host name of the write-side server to set up the Java Message Service. Specify the host name of the write-side server for the write application, and the host name of the read-side server for the read application. For example: <databases> <database dialect="db2" xa="true" database-name="document" database-type="documentstore" id="doc1" host-name="write-host" port-number="50000" max-pool-size="5" instance-name="db2" /> <database dialect="db2" xa="true" database-name="writesto" database-type="writestore" id="write1" host-name="write-host" port-number="50000" max-pool-size="5" instance-name="db2" /> <database dialect="db2" xa="false" database-name="itemretr" database-type="itemretrievalstore" id="item1" host-name="read-host" port-number="50000" max-pool-size="5" instance-name="db2" /> </databases> <jms-server application-name="write" host-name="write-host" port="1414"> 26 Windows Deployment Guide

31 <jms-topics> <jms-topic id="ar" /> </jms-topics> </jms-server> <applications> <application name="write" host-name="write-host"> <lucene-indexes> </lucene-indexes> <wars> Within the read application element, set the full paths to the locations where the Intelligence Analysis Platform stores the main search index and the alternative terms. For example: <application name="read" host-name="read-host"> <lucene-indexes> <lucene-index id="ar" main-index-location="c:\iap-data\ar\main_index" alternatives-location="c:\iap-data\ar\alternatives" /> </lucene-indexes> Save your changes and close topology.xml. Results Your topology file is now set to deploy a two server implementation of the Intelligence Analysis Platform with an English locale that uses the default alternative term index. What to do next Specifying credentials Depending on your requirements, you can continue with your deployment with the specified structure. Alternatively you can customize your topology in one of the following ways: v v To change the locale of your index, see Specifying the index language on page 63 To change the default terms in the index, see Creating a custom alternative term index on page 63 The databases and application server profiles in a deployment of the Intelligence Analysis Platform secure their content with user names and passwords. The scripts that interact with these components use credentials that are stored in the credentials.properties file. Before you begin There are two ways to approach credentials.properties. You can modify the example file in the deployment toolkit, or you can use the deployment scripts to generate a skeleton file. If you use the scripts, you must complete your changes to topology.xml before you generate credentials.properties. About this task For each authentication point that is identified in topology.xml, you must specify a user name and a password in the credentials.properties file. The deployment Chapter 6. Configuring the environment and the applications 27

32 scripts use this file when they interact with the components of the Intelligence Analysis Platform. When the platform is deployed and operating normally, you can delete credentials.properties. Important: It is seldom appropriate to retain a permanent, unencrypted record of user names and passwords. The credentials.properties file stores credentials in the following format: type.component.user-name=user name type.component.password=password The name of each credential has three parts: Part type component user-name or password Description The type of component that the credential is linked to: v db, for a database instance v websphere, for a WebSphere profile The database identifier or the WebSphere profile name Indicates whether the value is a user name or a password For example: db.doc1.user-name=admin db.doc1.password=password Procedure The deployment toolkit includes an example credentials.properties file that contains credentials for a two-server deployment of the Intelligence Analysis Platform that uses DB2 databases. Optionally, and especially if your deployment uses a different database management system, you can create a skeleton file from your topology definition. 1. Optional: If you want to overwrite the example credentials.properties file, rather than edit it: a. Open a command prompt on the write-side server, and navigate to IAP-Deployment-Toolkit\scripts. b. Run the following command to create a skeleton credentials file: python deploy.py -s write -t generate-credentials-file The command stores the new credentials.properties file in place of the example. The names of the credentials that the file contains are derived directly from topology.xml. 2. Using a text editor, open the IAP-Deployment-Toolkit\configuration\ environment\credentials.properties file. 3. If necessary, modify the list of credential names, and then enter the user names and passwords to use with each component. Important: The user names and passwords that you specify for WebSphere Application Server Full profile here must match the credentials that you provide when you configure WebSphere security later in the deployment procedure. Note: If you are using a SQL server, the specified database user name must have SQL Server Authentication as the authentication method. 28 Windows Deployment Guide