ANSYS EKM Installation Guide PDF

ANSYS EKM Installation Guide
ANSYS, Inc. Release 17.0

Southpointe January 2016
2600 ANSYS Drive
Canonsburg, PA 15317 ANSYS, Inc. is
ansysinfo@ansys.com certified to ISO
9001:2008.
http://www.ansys.com
(T) 724-746-3304
(F) 724-514-9494
Copyright and Trademark Information
© 2015 SAS IP, Inc. All rights reserved. Unauthorized use, distribution or duplication is prohibited.
ANSYS, ANSYS Workbench, Ansoft, AUTODYN, EKM, Engineering Knowledge Manager, CFX, FLUENT, HFSS, AIM
and any and all ANSYS, Inc. brand, product, service and feature names, logos and slogans are registered trademarks
or trademarks of ANSYS, Inc. or its subsidiaries in the United States or other countries. ICEM CFD is a trademark
used by ANSYS, Inc. under license. CFX is a trademark of Sony Corporation in Japan. All other brand, product,
service and feature names or trademarks are the property of their respective owners.
Disclaimer Notice
THIS ANSYS SOFTWARE PRODUCT AND PROGRAM DOCUMENTATION INCLUDE TRADE SECRETS AND ARE CONFID-
ENTIAL AND PROPRIETARY PRODUCTS OF ANSYS, INC., ITS SUBSIDIARIES, OR LICENSORS. The software products
and documentation are furnished by ANSYS, Inc., its subsidiaries, or affiliates under a software license agreement
that contains provisions concerning non-disclosure, copying, length and nature of use, compliance with exporting
laws, warranties, disclaimers, limitations of liability, and remedies, and other provisions. The software products
and documentation may be used, disclosed, transferred, or copied only in accordance with the terms and conditions
of that software license agreement.
ANSYS, Inc. is certified to ISO 9001:2008.
U.S. Government Rights
For U.S. Government users, except as specifically granted by the ANSYS, Inc. software license agreement, the use,
duplication, or disclosure by the United States Government is subject to restrictions stated in the ANSYS, Inc.
software license agreement and FAR 12.212 (for non-DOD licenses).
Third-Party Software
See the legal information in the product help files for the complete Legal Notice for ANSYS proprietary software
and third-party software. If you are unable to access the Legal Notice, Contact ANSYS, Inc.
Published in the U.S.A.

Table of Contents
Using This Guide ......................................................................................................................................... vii
1. Glossary ............................................................................................................................................ vii
2. EKM Path Variables ............................................................................................................................. ix
3. Filesystem Path Conventions ............................................................................................................... ix
1. Introduction to EKM ................................................................................................................................ 1
1.1. Licensing and Access ........................................................................................................................ 1
1.2. License Usage ................................................................................................................................... 2
2. Overview of an EKM Server Installation ................................................................................................. 7
2.1. Deployment Options ........................................................................................................................ 7
2.2. How an EKM Server is Configured ...................................................................................................... 8
2.3. Steps for Setting Up an EKM Server ................................................................................................... 8
3. Planning Deployment for an EKM Server ............................................................................................. 11
4. EKM Server Prerequisites ...................................................................................................................... 15
4.1. Prerequisite Instructions ................................................................................................................. 15
4.1.1. Machine Prerequisites ............................................................................................................ 15
4.1.1.1. Minimum Hardware Requirements ................................................................................ 15
4.1.1.2. Supported Operating System Versions ........................................................................... 17
4.1.1.3. Required Software Applications ..................................................................................... 17
4.1.1.3.1. Database Server Versions ...................................................................................... 17
4.1.1.3.2. Required Software Applications for EKM ................................................................ 18
4.1.1.4. ANSYS Licensing ............................................................................................................ 18
4.1.1.4.1. ANSYS License Manager and EKM License Setup .................................................... 18
4.1.1.4.2. ANSYS Client Licensing Setup ................................................................................ 19
4.1.2. Prerequisite Operations .......................................................................................................... 19
4.1.2.1. Download the JDBC Driver for the Cluster Database Server ............................................. 19
4.1.2.1.1. MySQL (Default) .................................................................................................... 20
4.1.2.1.2. Oracle ................................................................................................................... 20
4.1.2.2. Create an EKM Server Account ....................................................................................... 20
4.1.2.2.1. Windows .............................................................................................................. 21
4.1.2.2.2. Linux .................................................................................................................... 21
4.1.2.2.3. Setting the Open Files Limit .................................................................................. 22
4.1.2.2.4. Setting the Max User Processes Limit ..................................................................... 22
4.1.2.2.5. Configuring Access to PAM Authentication ............................................................ 23
4.1.2.3. EKM Cluster Configuration Prerequisites ......................................................................... 24
4.1.2.3.1. Components of a Cluster Configuration ................................................................. 24
4.1.2.3.2. Manual Configuration of the Cluster File Server ..................................................... 25
4.1.2.3.2.1. Network File Service ..................................................................................... 26
4.1.2.3.2.2. Cluster File System ....................................................................................... 26
4.1.2.3.3. Manual Configuration of the Cluster Database Server ............................................ 26
4.1.2.3.4. Naming the Cluster and Cluster Nodes .................................................................. 27
5. Installing an EKM Server ....................................................................................................................... 29
5.1. Installing a New EKM Server ............................................................................................................ 29
5.1.1. Installation Requirements ....................................................................................................... 29
5.1.2. Running ANSYS EKM Server Product Installation ..................................................................... 31
5.2. Running a Silent Installation ............................................................................................................ 34
5.3. Special Instructions for Upgrade ...................................................................................................... 35
6. Post-setup ............................................................................................................................................. 37
6.1. Post-Setup Instructions ................................................................................................................... 37
6.1.1. Configure the EKM Server ....................................................................................................... 37
6.1.2. Set the Location of ANSYS 17.0 Applications ........................................................................... 38
Release 17.0 - © ANSYS, Inc. All rights reserved. - Contains proprietary and confidential information
of ANSYS, Inc. and its subsidiaries and affiliates. iii
Installation Guide
6.1.3. Set Up an X Server (Linux) ....................................................................................................... 38

6.2. Configure the MySQL Connector/J JDBC Driver (Optional) ............................................................... 39
6.3. Grant Database Privileges for Each Cluster Node on the Cluster Database Server .............................. 40
6.4. Manually Configure the JBoss Domain ............................................................................................. 40
6.5. Deploy the EKM Server Application to the Application Server .......................................................... 40
6.6. Manually Configure the Front-End Web Server ................................................................................. 41
6.7. Special Post-Setup Instructions for Upgrade .................................................................................... 41
6.8. After Installation and Post-setup ..................................................................................................... 42
6.8.1. Configuring Job Submission Queues ...................................................................................... 42
7. Installing a Front-End Web Server ........................................................................................................ 43
7.1. The Architecture of an EKM Server ................................................................................................... 43
7.2. Installing the Web Server and Load Balancer .................................................................................... 44
7.2.1. Using EKM with Apache HTTP Server and mod_cluster ............................................................ 45
7.3. Configuring the Web Server and Load Balancer ............................................................................... 46
7.3.1. mod_cluster (Apache) ............................................................................................................ 46
7.4. Configuring the Application Server ................................................................................................. 49
7.4.1. JBoss Setup ............................................................................................................................ 49
7.4.1.1. Configure JBoss mod_cluster ......................................................................................... 49
7.4.1.2. Configure JBoss Web Services ........................................................................................ 50
7.4.1.3. Configure JBoss Undertow (Optional) ............................................................................ 50
7.5. Configuring EKM to Communicate with the Web Server ................................................................... 51
7.6. Testing the Connection ................................................................................................................... 51
7.7. Enabling HTTP Compression ........................................................................................................... 52
7.7.1. Apache .................................................................................................................................. 52
7.8. Overview of Client-Web Server Communications ............................................................................. 52
7.8.1. SSL/TLS Certificates: Background ............................................................................................ 53
7.8.2. Enabling Secure Connections to the Web Server (Optional) ..................................................... 54
7.8.2.1. Creating an In-House Certificate Authority ..................................................................... 54
7.8.2.2. Creating and Installing a Test Certificate ......................................................................... 56
7.8.2.2.1. Generating a Certificate Signing Request (CSR) ...................................................... 57
7.8.2.2.2. Signing the CSR .................................................................................................... 58
7.8.2.2.3. Installing the Certificate on the Web Server ........................................................... 58
7.8.3. Enabling Secure Connections to JBoss for Single-Node EKM Server (Optional) ......................... 59
7.8.3.1. Creating and Installing a Test Certificate ......................................................................... 59
7.8.3.1.1. Generating a Certificate Signing Request (CSR) ...................................................... 59
7.8.3.1.2. Signing the CSR .................................................................................................... 60
7.8.3.1.3. Installing the Certificate on the Application Server ................................................. 60
7.9. Securely Connecting to EKM (Optional) ........................................................................................... 62
8. Configuring Login Authentication and Access Settings ....................................................................... 65
8.1. Configuring Login Authentication ................................................................................................... 65
8.1.1. Authenticating EKM Logins to an LDAP Server ........................................................................ 66
8.1.1.1. Configuring Standard LDAP Authentication ................................................................... 66
8.1.1.2. Configuring Proxy-based LDAP Authentication .............................................................. 68
8.1.2. Authenticating EKM Logins to Windows Active Directory ........................................................ 69
8.1.3. Authenticating EKM Logins to the Windows Operating System ................................................ 71
8.1.4. Authenticating EKM Logins to the Linux Operating System ..................................................... 71
8.2. How User Logins Work .................................................................................................................... 72
8.3. Configuring Login-related Access Settings ....................................................................................... 73
8.4. Configuring LDAP Mapping ............................................................................................................ 74
9. Installing and Configuring EnginFrame ................................................................................................ 79
9.1. EnginFrame System Requirements .................................................................................................. 80
9.2. Installing EnginFrame ..................................................................................................................... 82
iv of ANSYS, Inc. and its subsidiaries and affiliates.
Installation Guide
9.3. Configuring EKM to Work with EnginFrame ..................................................................................... 84

9.4. Troubleshooting Tips ...................................................................................................................... 85
10. Starting the EKM Server and Launching the Web Client .................................................................... 87
10.1. Service Mode and Console Mode .................................................................................................. 87
10.2. Starting and Stopping the EKM Server in Console Mode ................................................................ 88
10.3. Launching the EKM Web Client ...................................................................................................... 89
10.4. Registering and Running EKM as a Service ..................................................................................... 89
10.4.1. Service Names ...................................................................................................................... 89
10.4.1.1. Windows ..................................................................................................................... 89
10.4.1.2. Linux ........................................................................................................................... 91
10.4.2. Running EKM as a Service ..................................................................................................... 93
10.4.2.1. Windows ..................................................................................................................... 94
10.4.2.2. Linux ........................................................................................................................... 94
10.5. Evaluating EKM Log Files ............................................................................................................... 96
10.5.1. Log Files ............................................................................................................................... 96
10.5.1.1. JBoss Log Files ............................................................................................................. 96
11. Upgrading an EKM Server from a Previous Version ............................................................................ 99
11.1. Variables and Common Commands ............................................................................................... 99
11.1.1. EKM Path Variables ............................................................................................................... 99
11.1.2. Common Commands ......................................................................................................... 100
11.2. Prerequisites ............................................................................................................................... 102
11.3. Steps for Upgrading an EKM Server ............................................................................................. 102
11.3.1. Prepare the EKM 16.0 Server for an Upgrade ....................................................................... 102
11.3.1.1. Verify the Existing EKM 16.0 Installation ...................................................................... 102
11.3.1.2. Back Up EKM 16.0 ...................................................................................................... 103
11.3.2. Prepare the EKM Database for an Upgrade – Part 1 .............................................................. 103
11.3.3. Set Up a New EKM 17.0 Server for an Upgrade ..................................................................... 105
11.3.4. Prepare the EKM Database for an Upgrade – Part 2 .............................................................. 105
11.3.5. Pre-Upgrade Instructions .................................................................................................... 105
11.3.6. Launch the Upgrade Wizard ................................................................................................ 106
11.3.7. Run the Upgrade Wizard ..................................................................................................... 106
11.3.8. Review the Post-Upgrade Instructions ................................................................................. 110
11.3.9. Post-Upgrade Instructions .................................................................................................. 110
11.3.9.1. Synchronize the Repository Folders on All Cluster Nodes ............................................ 111
11.3.9.2. Synchronize the Revision ID for All Cluster Nodes in the Cluster Database ................... 112
12. Gathering Support Diagnostics ........................................................................................................ 115
12.1. Launching the EKM Server Diagnostics Tool ................................................................................. 115
12.2. Using the EKM Server Diagnostics Tool ........................................................................................ 115
13. Uninstalling an EKM Server ............................................................................................................... 117
13.1. Uninstalling an EKM Server on Windows ...................................................................................... 117
13.2. Uninstalling an EKM Server on Linux ............................................................................................ 118
13.3. Uninstalling the Front End Web Server ......................................................................................... 118
14. Appendices ........................................................................................................................................ 119
14.1. Appendix A: Setting Environment Variables for EKM ..................................................................... 119
14.2. Appendix B: Network Ports .......................................................................................................... 120
14.3. Appendix C: JBoss Domain Mode and Configuration .................................................................... 120
14.3.1. Domain Mode .................................................................................................................... 121
14.3.2. Configuration ..................................................................................................................... 122
14.3.3. Management ..................................................................................................................... 122
14.3.3.1. Create JBoss Management Users ................................................................................ 122
14.3.3.2. Deploy the EKM Server Application ............................................................................ 124
14.3.4. JBoss Domain Controller – Failure and Promotion ............................................................... 127
of ANSYS, Inc. and its subsidiaries and affiliates. v
Installation Guide
14.4. Appendix D: Email Configuration ................................................................................................. 128

14.5. Appendix E: Resolving Network Port Conflicts .............................................................................. 129
14.6. Appendix F: Changing the JBoss HTTP Port .................................................................................. 130
14.7. Appendix G: Setting the HTTP Session Timeout ............................................................................ 131
14.8. Appendix H: Changing the MySQL Database Server Port .............................................................. 132
14.9. Appendix I: Configuring Windows Services (Windows Only) ......................................................... 133
14.10. Appendix J: Updating EKM Server Objects .................................................................................. 134
14.11. Appendix K: Granting Database Privileges .................................................................................. 135
14.12. Appendix L: Clearing the Repository .......................................................................................... 136
14.13. Appendix M: Disabling HTTP Compression ................................................................................. 136
14.14. Appendix N: Changing the JVM Heap Size .................................................................................. 137
14.15. Appendix O: Configuring EKM to Use Amazon S3 Data Storage ................................................... 138
14.16. Appendix P: Creating a Silent Installation File ............................................................................. 139
14.16.1. Silent Installation Options ................................................................................................. 139
14.16.2. Example Silent Installation Files ........................................................................................ 143
14.17. Appendix Q: EKM Cluster Network Configuration ....................................................................... 145
14.18. Appendix R: Configuring the MySQL Connector/J JDBC Driver .................................................... 146
14.19. Appendix S: Changing the EKM Cluster Name ............................................................................ 147
14.20. Appendix T: Changing an EKM Cluster Node IP Address .............................................................. 148
14.21. Appendix U: Troubleshooting .................................................................................................... 149
vi of ANSYS, Inc. and its subsidiaries and affiliates.
Using This Guide
The ANSYS Engineering Knowledge Manager (EKM) Installation Guide tells you what you need to know
to install and set up EKM on Windows and Linux systems. It also includes instructions on how to upgrade
EKM from a previous version, and contains an Appendix with supplemental information for configuring
and troubleshooting EKM.
This guide is intended for use by system administrators and engineers with intermediate or better ex-
perience with Information Technology (IT) concepts and practices. Sections that require advanced IT
experience are marked as such. Throughout this guide, steps specific to Windows or Linux systems are
called out separately.
Before you start, you should familiarize yourself with common terms (p. vii), path variables (p. ix), and
filesystem path conventions (p. ix) that are used throughout the guide. Note that some chapters intro-
duce additional terms that are specific to that topic.
This guide contains the following chapters:

1. Glossary
2. EKM Path Variables
3. Filesystem Path Conventions
1. Glossary
Application Server
The machine that runs the EKM server application.
Batch Service
A service that handles the execution of batch jobs for EKM.
CA
Certificate Authority. A trusted third-party that verifies the identity of entities such as web servers, and
digitally signs SSL/TLS certificates for those entities.
Cache Service
A service provided by EKM that enables local caching of EKM files in a distributed environment.
Client Browser
Web browser on a client machine.
Cluster Database Server

The database server that hosts the EKM database in an EKM cluster.
Cluster File Server

The file server that hosts the EKM data directory in an EKM cluster.
Cluster Node
An installation of EKM that includes an application server with the EKM server application, that is part of
an EKM cluster.
Cluster Configuration
A configuration of EKM consisting of a front-end web server, a cluster database server, and one or more
cluster nodes that operate collectively as a single EKM server.
of ANSYS, Inc. and its subsidiaries and affiliates. vii
Using This Guide
CSR
Certificate Signing Request. A request from the web server to sign a SSL/TLS certificate.
Database Server
The database server where the EKM database is hosted.
EKM Server Account

The user account used to run server processes that are part of the Server Environment (p. viii).
Front-End Web Server

A web server that is configured to communicate with one or more EKM servers. Required for a multi-node
EKM server, optional for a single-node EKM server.
JAAS
Java Authentication and Authorization Service
LAN
Local Area Network
Multi-Node EKM Server

An EKM server with multiple EKM cluster nodes.
Non-Primary Node
An EKM cluster node that acts as a JBoss slave, and as a non-primary node for EKM cluster services.
Primary Node
The EKM cluster node that acts as the JBoss domain controller, and the primary node for EKM cluster services.
RAID
A RAID (redundant array of independent disks) is multiple disk drives configured to function as one logical
drive. RAID configurations are used to make redundant copies of data or to improve I/O performance by
striping large files across multiple physical drives.
SAN
Storage Area Network
Server Environment
The set of software components that provide the foundation upon which the EKM server or cluster com-
ponent runs.
Single-Node EKM Server

An EKM server with only one EKM cluster node.
SSL
Secure Sockets Layer
SSL/TLS certificate
A certificate that a web server must possess to support encrypted connections using HTTPS.
WAN
Wide Area Network
viii of ANSYS, Inc. and its subsidiaries and affiliates.
Filesystem Path Conventions
2. EKM Path Variables

This guide uses several EKM path variables as shorthand to describe locations of files or directories. In
most cases, these variables correspond to environment variables used by EKM for the same purpose. It
is not necessary to define these variables before installing EKM - in all cases, where an environment
variable needs to be set, explicit instructions will be given to do so.
The following are EKM path variables used in this guide along with their definitions:
• APACHE_HOME: The directory where Apache HTTP Server (web server) is installed.
• EKM_BIN: Location of EKM supplemental binaries: EKM_HOME/bin.
• EKM_HOME: The EKM server application home directory: EKM_ROOT170/ekm-server.
• EKM_ROOT: The base directory for the EKM server. This is shared by all EKM cluster nodes.
• EKM_ROOT170: The v170 directory under the EKM server base directory: EKM_ROOT/v170.
• EKM_NODE_ROOT: The base directory for an EKM cluster node.
• EKM_NODE_ROOT170: The v170 directory under the EKM cluster node base directory:
EKM_NODE_ROOT/v170.
• EKM_TEMP: The directory that EKM uses for temporary files.
• JAVA_HOME: The directory where the Java Development Kit (JDK) is installed.
• JBOSS_HOME: The directory where the JBoss application server is installed.
• EKMDB_ROOT: The EKM database server (MySQL) base directory.
• MYSQL_HOME: The directory where the MySQL database server is installed.
• REPOSITORIES_HOME: The directory containing the EKM repositories: EKM_NODE_ROOT170/re-

positories.
3. Filesystem Path Conventions

The following filesystem path conventions are used throughout this guide:
• Windows operating systems use the backslash “\” character as a filesystem path separator.
• Linux operating systems use the forward slash “/” character as a filesystem path separator.
• The Java programming language uses the forward slash character “/” as a universal filesystem path
separator in configuration files and program resources. The slash is converted to the underlying native
convention when used.
When discussing a filesystem path in a generic sense, such as to give the location of a file, the Java
notation will be used. This notation should be understood to be generic, and the reader should substitute
the native path separator for their operating system in actual usage.
When the native convention is required, such as to give the location of a file or directory that is operating-
system specific, the native convention is used.
of ANSYS, Inc. and its subsidiaries and affiliates. ix
Using This Guide
When displaying the content of configuration files, commands to run, or inputs to provide to a command,
follow the convention used in the example.
x of ANSYS, Inc. and its subsidiaries and affiliates.
Chapter 1: Introduction to EKM
EKM is the server application in the EKM family of software. Once it is installed and set up, it can be
accessed using a web client and from ANSYS Workbench.
EKM Server and the EKM web client are installed from an ANSYS EKM Server product installation.
See Installing a New EKM Server (p. 29) for details on how to set up an EKM server.
For general information about deploying and configuring an EKM server, see Overview of an EKM
Server Installation (p. 7). In Planning Deployment for an EKM Server (p. 11), you will learn about the
components of an EKM server and different deployment options you may utilize when deploying EKM.
The majority of this guide covers set up of a new EKM server. A separate chapter, Upgrading an EKM
Server from a Previous Version (p. 99), is devoted entirely to upgrading an EKM server from a previous
version.
Additional information on various topics related to EKM installation and set up is provided in the Ap-
pendices (p. 119).
1.1. Licensing and Access

When a user signs in to an EKM workspace, a license is checked out that is based on the access level
currently assigned to that user in that workspace (see Setting Up Users and Groups in the Administration
Guide).
License types and the privileges they hold are presented below. If you need help, contact your EKM
system administrator or ANSYS Technical Support representative.
Table 1.1: License Types/Access Levels
License Type/Access User Privileges User Restrictions

Level
Shared • Can be added to the admin group • No restrictions
• Can add and modify content in both a

My Data and Shared Data
• Can launch jobs, processes and

applications
Analyst • Can add and modify content in My • Cannot add/modify content in

Data Shared Data
• Can view and download content in

Shared Data
of ANSYS, Inc. and its subsidiaries and affiliates. 1
Introduction to EKM
• Can launch jobs, processes and

applications
Basic • Can view and download content in • Cannot add/modify content in

Shared Data Shared Data (limited actions
available)
• Has no access to My Data, the Extrac-

tion Monitor, or the Recycle Bin
• Cannot launch jobs, processes, or

applications
a
A user with a Shared license will not have access to the Administration section unless he or she is added to the admin group.
b
lf a user has been signed in to a workspace with a Basic license because his or her assigned Access level in that workspace is
Basic, he or she will not see My Data or the Extraction Monitor displayed in the interface. However, if a user has been signed in
to a workspace with a Basic license due to license fallback (as described in License Fallback When Licenses are Unavailable (p. 4)),
and his or her assigned Access level in that workspace is actually Shared or Analyst, he or she will see My Data and the Extraction
Monitor displayed in the interface, but will have only read-only access in those folders.
For more information about the My Data and Shared Data repository folders, see Navigating the Re-
pository in the User’s Guide.
In most cases the user will be connecting to their default workspace when they sign in to EKM. However,
if they are using a bookmarked URL, they may be connecting to a different workspace that is not their
default.
When a user signs out of EKM, his or her license is released, provided that it is not still being used. See
License Usage (p. 2) for details.
Note
• Only users with Shared access can be added to the admin group. Once added to this group,
their access level cannot be changed.
• A user can only perform an action on an object if he or she has both the appropriate license and
object-level permission to perform that action. For example, if a user is granted Modify permission
on an object in Shared Data, but only holds an Analyst license, the user will not be able to
modify the object, because the Analyst license does not allow editing in Shared Data. The
user would need a Shared license to modify that object.
Similarly, if a user is denied Modify permission on an object in Shared Data, but holds a
Shared license (which allows editing in Shared Data), that user will not be able to
modify that object. The user would need to be granted Modify permission on that object
at the object level.
1.2. License Usage

As mentioned in Licensing and Access (p. 1), an EKM user license is checked out when a user signs in
to EKM, and is released when the user signs out of EKM. This section explains how licenses are used
2 of ANSYS, Inc. and its subsidiaries and affiliates.
License Usage
when a user accesses an EKM workspace from multiple clients simultaneously, and when other applica-
tions or processes access EKM. It also explains how licensing is handled when users switch from one
workspace to another, or when desired licenses are not available.
License Usage by Users

An EKM user may open multiple connections to EKM simultaneously using a single EKM license with
some restrictions. Note that the restrictions described apply to a single EKM user opening multiple
connections with EKM. See Making Simultaneous Connections in the EKM User’s Guide for details.
For example, if a user is already connected to EKM from a web browser, and then connects to EKM from
Workbench no additional license is needed. The general rules are:
• An EKM license will be checked out when a user connects to EKM from any client (web browser, Workbench,
mobile)
• The same license will be used if the user connects to EKM from a different client
• The license will be checked in when the user disconnects from the last client
As an example, when user jsmith signs into EKM from a web browser, a license is checked out for
jsmith. If jsmith connects to EKM from Workbench, a new license is not checked out because there
is already an open connection to EKM for jsmith. If jsmith shuts down Workbench and disconnects
from EKM, the license remains checked out because jsmith is still signed in to EKM in the web browser.
The license will be released when jsmith signs out of the EKM web browser session because that is
the last client still connected to EKM.
Note
In Internet Explorer, Chrome, and Firefox, if a user closes the browser window instead of using
the Sign out action, they will not be signed out of EKM, and their license will not be imme-
diately released. Sign-out and license release will only occur after the session has timed out,
which by default is after 30 minutes of inactivity. Therefore it is strongly recommended that
users only use the Sign out action to sign out of EKM.
License Usage by Applications and Processes

The following applications and processes also require a license to run, because they connect to EKM
using “proxy connections”, which are connections to the EKM server made on behalf of a user:
• File Transfer Client. Used to upload files to or download files from EKM. See Uploading Files Using the File
Transfer Client in the EKM User’s Guide.
• File Transfer Client transfers using a Cache Server. See Using a Cache System for WAN Transfers in the EKM
User’s Guide.
• EKM Studio. Used to create lifecycles and process templates. See Defining Process Templates in EKM Studio
in the EKM User’s Guide.
• Data extraction. Occurs when you upload simulation files to EKM. See Automatic Extraction of Data on Upload
in the EKM User’s Guide.
Introduction to EKM
Generally, these proxy connections never need to check out a license because they are always made
on behalf of a user who has already signed in to EKM (and therefore checked out a license). However,
if the user signs out of EKM and one of these applications/processes is still open or running, the license
will remain checked out.
Assume, for example, that a user has signed in to EKM using a web browser, and has therefore checked
out a license. If that user chooses to upload a folder of files using the File Transfer Client, the File
Transfer Client connects to EKM using the license that is already checked out for the user. If the user
signs out of EKM, and the File Transfer Client is still uploading files, the license will remain checked out
until the upload finishes and the user closes the File Transfer Client.
Note
If the File Transfer Client or EKM Studio is still running when a user signs out of EKM, it is
important that the user close the application window properly when he or she is finished
with it. Otherwise, the license will remain checked out until the session times out (30 minutes
by default).
License Usage Across Multiple Workspaces

If your EKM server has multiple workspaces, the following behavior is observed when a user switches
from one workspace to another:
• When a user signs in to an EKM initially, they are signed in to their default workspace (as determined by the
system administrator). The license type checked out depends on the access level assigned to that user in
that workspace.
• If the user switches to another workspace, and the access level assigned to the user in that workspace is the
same, the same license will continue to be used.
• If the user switches to another workspace, and the access level assigned to the user in that workspace is
lower, the same license will continue to be used, but the user’s privileges will be restricted according to his
or her assigned access level.
• If the user switches to another workspace, and the access level assigned to the user in that workspace is
higher, EKM will attempt to check out the higher-level license, and if successful, will release the initial, lower-
level license. If the attempt is unsuccessful, the initial license will remain checked out, and the user will have
the permissions of that license in the current workspace. For example, if a user currently has an Analyst
license checked out, and switches to a workspace in which he or she has been assigned Shared access,
but the checkout of a Shared license fails, the user will still have the privileges of an Analyst license in
the new workspace.
License Fallback When Licenses are Unavailable

If a user is assigned a Shared or Analyst license in a workspace, but none are available when that
user signs in or switches to that workspace, a Basic license will be checked out instead, and the user
will have limited access in that workspace. The following dialog box notifies the user of what has occurred:
License Usage
If the user clicks OK, he or she will remain signed in to the workspace with limited access. This means
that the user will only be able to view (and not modify) objects in Shared Data, as described in Licensing
and Access (p. 1).
If the user clicks Sign out, he or she will be signed out of all workspaces, and can try signing in again
later.
Chapter 2: Overview of an EKM Server Installation
An EKM server has the following features:
• Multi-user access (any number of users)
• Network access
• LDAP/AD/Windows OS/Linux OS authentication
• Email integration
• RSM integration
• PDM integration
• Distributed file caching
• MySQL and Oracle database support
• Support for external databases
• Clustering
• Apache web-server integration
Note
EKM servers are supported only on 64-bit operating systems.
The procedure for setting up an EKM server requires intermediate to advanced IT experience. For setup
steps, refer to Steps for Setting Up an EKM Server (p. 8).
2.1. Deployment Options

EKM servers can be deployed to serve any number of users. Each EKM server can be deployed in a
single-node or multi-node configuration, on one or more server hosts. Multiple EKM servers can be
deployed in a distributed fashion to serve large numbers of users in geographically separate locations.
The simplest scenario is to deploy EKM as a single-node server (p. viii) on a single host, where all services
(cluster database server, cluster node, and cluster file server) are on the same host.
More complex and powerful configurations are possible by separating services onto different hosts,
such as configuring EKM to access a cluster database server and cluster file server on other hosts. Addi-
tionally, the EKM server itself may be deployed as a multi-node server (p. viii), where multiple cluster
nodes work together to act as a single EKM server capable of handling more user requests. A front-end
web server is typically employed to provide load-balancing and a single point of access to an EKM
server, whether the EKM server is single-node or multi-node.
Overview of an EKM Server Installation
Additionally, you can configure a shared EKM server to use an external authentication service such as
LDAP or Windows Active Directory or to use Windows/Linux OS-based authentication to simplify man-
agement and reduce the number of passwords users need to keep track of. See Configuring Login Au-
thentication and Access Settings (p. 65) for more details.
Finally, multiple EKM servers can be combined in a distributed deployment to serve users in geograph-
ically separate locations. In a distributed deployment, EKM servers in each location serve local users,
and provide distributed file caching for data residing in other locations.
Some of the components of an EKM server deployment are configured manually, and others are set up
automatically during EKM server setup. Advanced configurations provide higher performance and
availability, but require advanced IT experience to configure and administer. The ANSYS Worldwide
EKM Enterprise Team can help you plan and execute a successful EKM deployment that takes advantage
of EKM’s flexible deployment options to meet your organization’s needs now and in the future.
2.2. How an EKM Server is Configured

Every EKM server is configured in a cluster configuration, even if only a single cluster node is installed.
A cluster configuration is made up of multiple cluster components that can be set up flexibly across
one or more server hosts. Cluster configuration is designed to be adaptable and expandable to meet
your organization’s evolving needs.
An EKM server configuration consists of the following components:
• One cluster file server (p. vii)
• One cluster database server (p. vii)
• One or more cluster nodes (p. vii)
• One front-end web server (p. viii)1.
These components collectively form a single EKM server in a cluster configuration. The cluster file
server is configured manually first. Next, the cluster database server is configured manually, if applicable.2.
Next, the ANSYS EKM Server product installation (p. 29) is run to set up the cluster database server and
each cluster node. Finally, the front-end web server is set up manually after the cluster nodes have been
set up.
Refer to the Planning an EKM Deployment (p. 11) chapter for more information on server configuration
options.
2.3. Steps for Setting Up an EKM Server

The procedure for setting up an EKM server provides flexibility to deploy EKM in a variety of enterprise
configurations. An EKM server can be configured to use the default MySQL database server or an existing
database server. More advanced configurations are possible, depending on your needs.
Follow these steps to set up an EKM server:
1
A front-end web server is optional for a single-node EKM server, but required for a multi-node EKM server.
2
The cluster database server is configured manually if using an existing database server. ANSYS EKM Server product installation can
install a default MySQL database server as the cluster database server, or use an existing database server you manually configure.
Steps for Setting Up an EKM Server
1. Plan the EKM server deployment.
2. Review and fulfill the prerequisites.
3. Install the EKM server (p. 29).
4. Review the post-setup requirements (p. 37).
5. (Optional) Install a front-end web server (p. 43).
6. Set up login authentication and repository access (p. 65).
Chapter 3: Planning Deployment for an EKM Server
Every EKM server is deployed in a cluster configuration, which provides flexible deployment options.
Cluster configuration allows EKM to scale and adapt to serve different workloads, and can be configured
for fault-tolerance.
An EKM server cluster configuration consists of the following cluster components:
• One cluster file server (p. vii).
• One cluster database server (p. vii).
• One or more cluster nodes (p. vii).
• (Optional) One front-end web server (p. viii).1
These components collectively form a single EKM server in a cluster configuration. The cluster components
may be installed on any combination of server hosts, from a single server host to multiple server hosts.
At a minimum, an EKM server must have a single cluster node. An EKM server with only a single cluster
node is referred to as a single-node server (p. viii). This deployment option allows you to start with a
simple deployment, and to expand by deploying additional cluster nodes as your needs grow.
An EKM server with multiple cluster nodes is referred to as a multi-node server (p. viii). A multi-node
server provides the following benefits:
• High availability: If an EKM cluster node fails, other cluster nodes in the cluster are still able to serve EKM
users.
• Scalability: The number of simultaneous users supported by an EKM server increases (scales up) as you add
cluster nodes.
• Load balancing: Connections to an EKM server are load balanced to ensure that users are spread evenly
across the cluster nodes, optimizing performance for any given number of users.
In a multi-node EKM server, multiple cluster nodes are grouped together to appear as if they were a
single, larger server. Incoming requests from users (clients) all come in to a common URL. From there,
clients are connected to individual cluster nodes. The cluster nodes share a common cluster database
server, a common cluster file server, and a common front-end web server that acts as a load balancer.
The load balancer distributes user sessions so that for any number of users accessing the EKM server,
the sessions will be spread more or less evenly across the nodes in the cluster.
One cluster node in a cluster configuration is designated the primary node (p. viii). The primary node
provides centralized configuration and management for the cluster. Each additional node is called a
non-primary node (p. viii). All cluster nodes run the EKM server application and handle user requests.
1
The front-end web server is optional for a single-node EKM server, but is required for a multi-node EKM server.
Planning Deployment for an EKM Server
When installing the EKM server using ANSYS EKM Server product installation, you will install one required
primary node, and one or more optional non-primary nodes.
Note
The front-end web server is optional for a single-node EKM server, but is required for a multi-
node EKM server.
In a cluster, the configuration of the EKM server can vary depending on where the components are set
up. Two example configurations are shown in the figures below (Figure 3.1: Cluster: Example 1 (p. 12)
and Figure 3.2: Cluster: Example 2 (p. 13)).
Figure 3.1: Cluster: Example 1
Figure 3.2: Cluster: Example 2
Understanding your goals for setting up an EKM server will help determine how to deploy the compon-
ents. Each deployment of EKM is unique, given the different goals (scalability, fault-tolerance), and re-
sources available in each situation. Careful consideration should be given to how to set up each of the
cluster components to best meet your EKM server deployment goals.
Chapter 4: EKM Server Prerequisites
In order to set up a new EKM server, certain prerequisites must be fulfilled before you run the ANSYS
EKM Server product installation (p. 29). While running the product installation, you will be prompted
to review and fulfill these requirements in the Prerequisites step, before you can go to the next step
of the installation.
When planning a production deployment of EKM, it is recommended that you have your ANSYS Account
Manager schedule a meeting with the Worldwide EKM Enterprise Team. The Worldwide EKM Enterprise
team will help you determine resource requirements based on your workloads and deployment goals,
and will work with you to plan and execute a successful EKM deployment that is tailored to your organ-
ization’s unique needs.
4.1. Prerequisite Instructions

The following prerequisites must be fulfilled and operations performed before you can set up an EKM
server using the ANSYS EKM Server product installation (p. 29). You will be prompted to confirm that
these prerequisites are fulfilled in the Prerequisites step of the product installation.
Important
Failure to fulfill prerequisites will result in errors in the setup process.
This chapter covers the following prerequisites:
• Machine Prerequisites (p. 15)
• Prerequisite Operations (p. 19)
4.1.1. Machine Prerequisites

The following machine prerequisites must be met before you can set up an EKM server using the ANSYS
EKM Server product installation.
4.1.1.1. Minimum Hardware Requirements

Minimum hardware requirements for different configurations are provided below, along with common
hardware requirements that apply to all configurations.
The Worldwide EKM Enterprise team can provide more specific resource recommendations for your
EKM deployment based on your organization’s workloads and deployment goals.
Common Hardware Requirements
• RAM: 8 GB or more RAM is required.
EKM Server Prerequisites
• CPU: A minimum of 2 CPU cores of 2.0 GHz or higher CPU speed are required. Additional CPU cores will
provide better performance.
• Graphics Card: A workstation-class graphics card that is certified to be compatible with ANSYS Inc.
products (for example, NVIDIA Quadro and AMD FirePRO).
Note
The amount of memory (RAM) and processing power (CPU) required for an EKM server
is largely determined by a combination of the following factors:
1. The amount of RAM and CPU required to run the EKM server itself. This includes the applic-
ation server, database server, and so on that make up the EKM server environment.
This factor increases with the number of users that access the system concurrently,
and is affected by the types of activities performed by the users, such as searching,
viewing reports, or browsing the repository. If we assume that users use the server
in more or less similar ways, the amount of RAM and CPU required by the EKM
server to support multiple users should scale more or less linearly as concurrent
users are added. For certain workloads, in terms of number of concurrent users, this
factor can be viewed as a more or less fixed cost.
2. The amount of RAM and CPU required to execute external applications on the EKM server
itself. External applications, such as ANSYS Workbench, are executed on the EKM server
when simulation files are added to the EKM repository, in order to perform data extraction
on those files. The amount of RAM and CPU required to perform these actions varies con-
siderably with the size, type, and complexity of the simulation data. For large or complex
simulation files, the cost in RAM and CPU to execute these external applications can be
considerable, and can be several times the amount of RAM and CPU required by the EKM
server itself, and the connected users, as described above. This can therefore be viewed as
a variable cost, depending on the size, type and complexity of the simulation data you will
be managing in EKM.
It is important to consider both of the above factors when determining how much RAM
and CPU an EKM server will need to run smoothly under the anticipated workload, and
with the size, type and complexity of the simulation data EKM will be managing.
The minimum hardware requirements presented in this section only account for the
RAM and CPU requirements for the EKM server, and do not account for the variable cost
of managing simulation data, which is highly dependent on the simulation data itself.
Cluster File Server
Disk space
• EKM base directory: At least 40 GB of disk space for storing the EKM server and applications.
• EKM data directory: Disk space required depends on the amount of data you archive in EKM, and could
range from several GB to several TB depending on your requirements. Contact the Worldwide EKM Enterprise
team for assistance with resource planning, or provide at least 200 GB of disk space for the EKM data directory.
• EKM job directory: Disk space required depends on the size and quantity of jobs you execute from EKM, and
could range from several GB to several TB depending on your requirements. Contact the Worldwide EKM
Prerequisite Instructions
Enterprise team for assistance with resource planning, or provide at least 200 GB of disk space for the EKM
job directory.
Cluster Database Server
Disk space
• EKM database: At least 40 GB of disk space for storing the EKM database and applications.
Cluster Node (each)
RAM and CPU
• RAM: 8 GB or more RAM is required.
• CPU: A minimum of 2 CPU cores of 2.0 GHz or higher CPU speed are required. Additional CPU cores will
provide better performance.
Disk space
• EKM cluster node base directory: At least 40 GB of disk space for storing the EKM server and search index.
• EKM temp directory: At least 40 GB of disk space for temp files.
Note
These requirements apply to EACH cluster node. For example, if a host has 2 cluster nodes
installed, the host should have 16 GB or more of RAM, 4 or more CPU cores, 80 GB or more
disk space for the 2 cluster nodes, and 80 GB or more disk space for temp files.
Disk space
• At least 10 GB of disk space for storing the installed applications, logs and temp files.
4.1.1.2. Supported Operating System Versions

EKM is designed to run on Windows and Linux operating systems. For a current list of supported oper-
ating system versions, visit the ANSYS Customer Portal:
https://support.ansys.com
4.1.1.3. Required Software Applications

The following required software application prerequisites must be fulfilled before you can set up an
EKM server using the ANSYS EKM Server product installation.
4.1.1.3.1. Database Server Versions

EKM uses a database server to store user and program data. ANSYS EKM Server product installation can
set up and configure a database server for use with EKM, or an existing database server can be configured
manually for use with EKM.
ANSYS EKM Server product installation can set up and configure the following database servers for EKM:
• MySQL version 5.5 (5.5.41)
EKM can use the following existing database servers:
• MySQL version 5.5 (5.5.41)
• Oracle 11g
4.1.1.3.2. Required Software Applications for EKM

EKM requires the following software applications to be installed in order to perform data extraction
from supported CAE simulation file formats:
• ANSYS Multiphysics Products Version 17.0. This includes ANSYS Structural Mechanical, ANSYS CFX,
ANSYS Fluent and ANSYS Workbench.
Note
The EKM File Transfer Client and Studio applications, which are launched via the Web Client,
must have Java Runtime Edition (JRE) 1.8.0_40 or higher installed.
4.1.1.4. ANSYS Licensing

EKM uses ANSYS Licensing. ANSYS Licensing consists of server and client components. In order to set
up ANSYS licensing for EKM, both server and client licensing setup steps need to be performed:
• ANSYS License Manager and EKM License Setup (p. 18)
• ANSYS Client Licensing Setup (p. 19)
4.1.1.4.1. ANSYS License Manager and EKM License Setup

In order to run EKM, an ANSYS License Manager must be available, and EKM licenses must be installed
and available for EKM to check out. Follow these steps to set up the ANSYS License Manager (Server)
and EKM licenses:
1. Make sure an ANSYS License Manager is available to serve the EKM licenses. If no ANSYS License
Manager is available, install it somewhere:
• The ANSYS License Manager that serves EKM licenses MUST use ANSYS License Manager version
17.0 or higher. The ANSYS License Manager can be installed by running ANSYS product installation.
• The ANSYS License Manager does not need to be installed on the same host as EKM, but it can be.
• If the ANSYS License Manager is on another host, that host must be reachable over the network
from the hosts where EKM is installed.
2. Install the EKM licenses on your ANSYS License Manager, and verify that they are recognized and
available. Refer to the ANSYS License Manager documentation for instructions.
• EKM license keys are tied to a specific license manager host. This means that the license keys can
only be loaded and served from the ANSYS License Manager running on the host that the license
keys are tied to. The License Manager host may or may not be the same host as the host you intend
to set up EKM on.
4.1.1.4.2. ANSYS Client Licensing Setup

EKM communicates with the ANSYS License Manager through ANSYS Client Licensing. ANSYS Client
Licensing MUST be installed on the system where the EKM server is set up1.
ANSYS Client Licensing is installed automatically when ANSYS Multiphysics is installed. ANSYS Multiphysics
is a prerequisite software application for EKM server, so any host where an EKM cluster node will be
setup should already have ANSYS Client Licensing. If for some reason ANSYS Client Licensing is not in-
stalled, ANSYS Client Licensing is available as a standalone installer from the ANSYS Customer Portal:
http://www.ansys.com/customerportal/index.htm. EKM uses ANSYS Client Licensing to check out EKM
licenses.
Note
The ANSYS License Manager and ANSYS Client Licensing can be safely installed on the same
machine.
To set up ANSYS Client Licensing:
1. Verify that ANSYS Client Licensing is installed. On Windows systems, there will be a Start Menu item for
ANSYS Client Licensing:
Start > ANSYS 17.0 > ANSYS Client Licensing
If ANSYS Client Licensing is not installed, install it.
2. Run the ANSYS Client Licensing admin utility. On Windows systems, there will be a Start Menu item for the
ANSYS Client Licensing admin utility:
Start > ANSYS 17.0 > ANSYS Client Licensing > Client ANSLIC_ADMIN Utility 17.0
Specify the location of the ANSYS License Manager serving the EKM licenses by clicking on the
button labeled: Specify the License Server Machine
and entering the hostname and network port of the ANSYS License Manager.
4.1.2. Prerequisite Operations

The following prerequisite operations must be fulfilled before you can set up an EKM server using the
ANSYS EKM Server product installation.
4.1.2.1. Download the JDBC Driver for the Cluster Database Server
In order for EKM to communicate with the database server hosting the EKM database, a JDBC (Java
Database Connectivity) driver for the database server is required. This driver must be downloaded before
running product installation. This section provides instructions for downloading JDBC drivers for sup-
ported database server types.
1
If the ANSYS License Manager is installed on the system where the EKM server will be set up, it is not necessary to install the ANSYS
Client Licensing, as the ANSYS License Manager also includes ANSYS Client Licensing.
JDBC drivers for each database server are available for download from the web site of the database
server vendor.
Note
The JDBC drivers used with EKM are known as “TYPE 4” drivers, also referred to as “thin”
drivers.
The EKM database server can be either MySQL (default) or Oracle.
Follow the instructions for installing the JDBC driver for the selected EKM database server type.
4.1.2.1.1. MySQL (Default)
The recommended JDBC driver for MySQL database server is MySQL Connector/J2. This driver can be
downloaded from the following URL:
http://dev.mysql.com/downloads/connector/j/
For production usage of EKM, it is recommended that you download and use the MySQL Connector/J
JDBC driver. The MySQL Connector/J driver is installed and configured manually after the EKM server
is installed.
4.1.2.1.2. Oracle
The recommended JDBC driver for Oracle database server is: JDBC Thin for All Platforms.
Driver files: ojdbc6.jar and orai18n.jar
This driver can be downloaded from the Oracle website: http://www.oracle.com
The Oracle JDBC driver files are required to complete an EKM server installation for use with Oracle.
The JDBC driver files will be requested during ANSYS EKM Server product installation.
4.1.2.2. Create an EKM Server Account

The EKM server account (p. viii) is a special dedicated user account that is used solely for running the
EKM server. The EKM server account must be created before running ANSYS EKM Server product install-
ation. Creation of user accounts and groups is typically performed by a system administrator.
Important
The ANSYS EKM Server product installation should be executed by the EKM server account
in order to ensure that the EKM server account has correct access permissions to all files
created during installation.
2
When MySQL is selected as the database server during ANSYS EKM Server product installation, the MySQL-compatible MariaDB
Connector/J driver is installed by default. This is a freely distributable driver that is compatible with MySQL. It is not the same as
MySQL Connector/J.
4.1.2.2.1. Windows
The EKM server account can be a Windows Active Directory account, or an account that is defined locally
on the host. If you will be connecting to external file servers from EKM, the EKM server account (p. viii)
must have the necessary privileges to access those external file servers.
If you plan to run EKM as a Windows service (the recommended way to run EKM), the following privileges
are required by the EKM server account:
1. The EKM server account must have Administrator privileges on the host.
2. The EKM server account must be granted the Log on as a service user right in the Local Security
Policy of the host.
To grant this right, go to the Windows Control Panel > Administrative Tools menu, and run
the Local Security Policy editor:
Find the setting:
Security Settings > Local Policies > User Rights Assignment > Log on as a service
and add the EKM server account to the list of accounts having this user right.
Note
If the EKM server account is a local account, the account must be defined and con-
figured identically on each EKM cluster node when deploying a multi-node EKM
server.
4.1.2.2.2. Linux
The EKM server account can be an account that is defined on the network, or an account that is defined
locally on the host. If you will be connecting to external file servers from EKM, the EKM server account
must have the necessary privileges to access those external file servers.
Note
The root user should not be used as the EKM server account.
In our example, it is assumed that an EKM server account has been created for this purpose:
User name ekm

Group ekm
Home directory /home/ekm
Note
If the EKM server account is a local account, the account must be defined and configured
identically on each EKM cluster node when deploying a multi-node EKM server.
4.1.2.2.3. Setting the Open Files Limit

The maximum number of open file descriptors that a process can have on a Linux operating system is
governed by system and per-user limits. File descriptors are used by a process to access files as well as
network connections. For an application like EKM that makes intensive use of files and network connec-
tions, it is necessary to increase the open files limit beyond the default settings that are set in the op-
erating system.
It is typically necessary to increase the per-user limit for the EKM server account so that the EKM server
processes can run with an appropriate limit. It is rarely necessary to change the system open files limit.
Per-user limits are defined in terms of "soft" and "hard" limits - see your operating system's document-
ation for more information on these terms.
To show the soft limit for open files for the EKM server account, open a shell as the EKM server account,
and execute the following command:
ulimit -n
To show the hard limit for open files for the EKM server account, open a shell as the EKM server account,
and execute the following command:
ulimit -H -n
It is recommended that you set the EKM server account's open files limits as follows:
soft limit: 4096
hard limit: 65535
To set per-user open files limit for the EKM server account, edit the file:
/etc/security/limits.conf
Add the following lines to define open files limits for the EKM server account:
ekm soft nofile 4096
ekm hard nofile 65536
4.1.2.2.4. Setting the Max User Processes Limit

The maximum number of processes and threads that a user can create on a Linux operating system is
governed by system and per-user limits. EKM launches multiple processes and threads in the course of
its normal operation, so it is necessary to increase the max user processes limit beyond the default
settings that are set in the operating system.
It is typically necessary to increase the per-user max user processes limit for the EKM server account so
that the EKM server processes can run with an appropriate limit. It is rarely necessary to change the
system max user processes limit. Per-user limits are defined in terms of "soft" and "hard" limits—see
your operating system's documentation for more information on these terms.
To show the soft limit for max user processes for the EKM server account, open a shell as the EKM
server account, and execute the following command:
ulimit -u
To show the hard limit for max user processes for the EKM server account, open a shell as the EKM
server account, and execute the following command:
ulimit -H -u
It is recommended that you set the EKM server account's max user processes limits as follows:
soft limit: 4096
hard limit: 119368
To set per-user max user processes limit for the EKM server account, edit the file:
/etc/security/limits.conf
Add the following lines to define max user processes limits for the EKM server account:
ekm soft nproc 4096
ekm hard nproc 119368
4.1.2.2.5. Configuring Access to PAM Authentication

EKM server on Linux is configured by default to authenticate EKM logins to the operating system using
PAM (see Configuring Login Authentication and Access Settings (p. 65)).
The EKM server account needs to be granted access to certain operating system files so that it can au-
thenticate EKM logins to the operating system via PAM. To configure access to PAM for the EKM server
account, follow these steps:
1. Create, or verify the existence of a group called shadow in the file /etc/group. For example:
shadow:x:15:
If creating a new group, make sure the GID is unique, that is, the GID is not used by any other
local group or NIS group (if applicable).
2. Add the root user and the EKM server account to the shadow group. In the example below, the root
and ekm users are members of the shadow group:
shadow:x:15:root,ekm
3. Set the ownership and file permissions of /etc/shadow to restrict access to only the root user and
the shadow group:
-sh-4.1# chmod 640 /etc/shadow
-sh-4.1# chown root:shadow /etc/shadow
Verify the ownership and file permissions:

-sh-4.1# ls –la /etc/shadow
-sh-4.1# -rw-r----- 1 root shadow 1021 Oct 13 14:49 /etc/shadow
The EKM server account also needs read access to the directory /etc/pam.d and its contents. It is
not normally necessary to change the permissions of /etc/pam.d or its contents, as they will already
be readable by default.
4.1.2.3. EKM Cluster Configuration Prerequisites

EKM is deployed in a cluster configuration, to provide flexibility and expandability. This section documents
the prerequisites for deploying EKM in a cluster configuration. These prerequisites must be completed
before installing EKM using ANSYS EKM Server product installation.
4.1.2.3.1. Components of a Cluster Configuration

An EKM server cluster configuration consists of the following components:
• One cluster file server (p. vii). The cluster file server provides shared file storage for the EKM cluster.
• One cluster database server (p. vii). The cluster database server provides the EKM database for the EKM
cluster.
• One or more cluster nodes (p. vii)3. Each cluster node runs an instance of the EKM server application.
• One front-end web server (p. viii). The front-end web server is the main point of access to the EKM cluster,
and provides load-balancing.
These cluster components collectively form a single EKM server in a cluster configuration. Now, carefully
read the information in Server Environment (p. 24) and Requirements for a Cluster Configuration (p. 25)
below to find out more about the server environment and requirements for cluster components.
Server Environment
The server environment for an EKM cluster component is the set of software components that provides
the foundation upon which the cluster component runs. Some cluster components, such as the cluster
database server4 and cluster nodes, are set up using the ANSYS EKM Server product installation, which
sets up the cluster components along with their server environments. These cluster components are
set up in the locations you specify in the product installation, and are configured according to inputs
you provide. Other cluster components, such as the cluster file server and front-end web server, require
manual set up of their server environments.
Server environment for the cluster file server (set up manually); either:
• Network File Service: NFS (Linux) or CIFS/SMB (Windows)
• Cluster File System: GPFS (Linux)
Server environment for the cluster database server; either:
• MySQL Database Server version 5.5.41 (set up by the ANSYS EKM Server product installation)
• MySQL or Oracle database server (set up manually)5
Server environment for a cluster node (set up by the ANSYS EKM Server product installation):
• WildFly (JBoss) Application Server version 8.2.0.Final
3
One cluster node is designated as the EKM cluster primary node. This cluster node provides centralized configuration and management
of the EKM cluster.
4
The cluster database server may also be set up manually.
5
For a list of the compatible database servers, see Database Server Versions (p. 17).
• Sun Java Development Kit (JDK) version 1.8.0_40
• Java Service Wrapper version 3.2.3 (Windows only)
Server environment for the front-end web server (set up manually):
• Apache HTTP Server 2.2.x or 2.4.x
Requirements for a Cluster Configuration
• It is required that all cluster components be installed on the same physical LAN. Cluster components may
not be spread out across a WAN.
• It is required that all cluster nodes be installed on the same operating system architecture (Windows or
Linux).
• It is required that the cluster file server use a compatible network file server or cluster file system to serve
the shared directories used by the cluster.
• It is not required that the operating system architecture of the cluster database server match that of the
cluster nodes.
• It is not required that the operating system architecture of the front-end web server match that of either
the cluster database server or the cluster nodes.
The cluster file server, cluster database server, cluster nodes and front-end web server may be installed
on any combination of hosts, as long as these requirements are met.
Important
It is important that all server hosts in an EKM server cluster configuration are configured to
synchronize their system clocks with a reliable time source, using a time service provided by
the operating system. This will help prevent data consistency issues that could arise from
time differences between cluster components such as the cluster database server, cluster
file server and cluster nodes. Example time services include Windows Time Service (Windows)
and ntpd (Linux).
4.1.2.3.2. Manual Configuration of the Cluster File Server

The cluster file server provides shared file storage for the cluster either through a compatible network
file service like NFS or CIFS/SMB, or through a compatible cluster file system such as GPFS. The cluster
file server is a role that can be fulfilled by a single server host or multiple server hosts, depending on
the cluster configuration and the service(s) used to fulfill this role.
Each cluster node in a clustered configuration of EKM runs an instance of the EKM server application.
The EKM server application process runs under the account credentials of the EKM server account, and
accesses shared directories provided by the cluster file server using the account credentials of the EKM
server account. This means that the EKM server account must be recognized as a valid account on the
cluster file server.
The cluster file server must meet the following requirements:
• The EKM server account used on the cluster nodes must be recognized as a valid account on the cluster file
server.
• The EKM server account must have read/write permission to the shared directories for the EKM cluster on
the cluster file server.
The EKM server is configured to use the cluster file server during ANSYS EKM Server product installation
by specifying paths on the cluster file server during product installation.
The cluster file server provides centralized, shared storage for the following EKM directories:
• Base directory for the EKM server: This directory is the home for the EKM server application, and contains
common files and configuration that are used by all cluster nodes.
• EKM data directory: This directory contains the EKM datastore, the central file storage area where data
archived in EKM is stored.
• EKM jobdata directory: This directory contains job data for jobs submitted to RSM.
It is necessary to configure the cluster file server and set up shared storage for these directories before
running the ANSYS EKM Server product installation. The cluster file server can provide this shared
storage using a compatible network file service or cluster file system.
4.1.2.3.2.1. Network File Service
The cluster file server can use a compatible network file service to provide a network file share for use
by the EKM cluster. On Linux, the cluster file server serves this file share using NFS. On Windows, the
cluster file server serves this file share using CIFS/SMB. Configuring the cluster file server component
consists of configuring a network file share that will be used by the EKM cluster.
EKM is compatible with the following network file services:
• NFS (Linux)
• CIFS/SMB (Windows)
4.1.2.3.2.2. Cluster File System
The cluster file server can use a compatible cluster file system to provide a shared file system for use
by the EKM cluster. On Linux, the cluster file server can use the GPFS cluster file system. Configuring
the cluster file server consists of configuring a cluster file system that will be used by the EKM cluster.
EKM is compatible with the following cluster file systems:
• GPFS (Linux)
4.1.2.3.3. Manual Configuration of the Cluster Database Server

The cluster database server can be either a default MySQL database server set up and configured by
ANSYS EKM Server product installation, or an existing database server that is configured manually for
use with EKM.
If the cluster database server will be a default MySQL database server set up and configured by product
installation, this prerequisite can be skipped.
If the cluster database server is an existing MySQL or Oracle database server, follow these steps to
manually configure the cluster database server:
1. (MySQL) Configure the cluster database server. (p. 27)
2. Create the EKM database on the cluster database server. (p. 27)
3. Grant database privileges for each EKM cluster node on the cluster database server. (p. 27)
(MySQL) Configure the cluster database server:
If the cluster database server is an existing MySQL database server, the MySQL database server must
be configured with the following options in the MySQL defaults file MYSQL_HOME/my.(cnf|ini):
[mysqld]
default_storage_engine=INNODB
transaction_isolation=READ-COMMITTED
max_allowed_packet=128m
Create the EKM Database:
Follow the instructions for your database server to create the EKM database. You will provide the details
for accessing the EKM database during ANSYS EKM Server product installation, such as the cluster
database server hostname and port, the name of the EKM database, and the account name and password
for accessing the EKM database.
Grant database privileges for each cluster node on the cluster database server:
Each EKM cluster node requires database privileges on the cluster database server in order to access
and modify the EKM database. For instructions on granting database privileges on a MySQL database
server, refer to Appendix K: Granting Database Privileges (p. 135). Follow the instructions to grant database
privileges to the EKM database for each EKM cluster node.
For instructions on granting database privileges on an Oracle database server, consult the Oracle database
server documentation.
4.1.2.3.4. Naming the Cluster and Cluster Nodes

This section explains what a cluster name and node name are, how they are used, and provides some
restrictions on how they can be named in the ANSYS EKM Server product installation.
EKM cluster nodes locate one another on a LAN using an automatic discovery mechanism. This makes
it easy to add new cluster nodes to an EKM server, and allows cluster nodes to join and leave the cluster
automatically as they are started and stopped.
There are two levels of naming within a cluster: cluster name and node name:
1. Each EKM server has a cluster name. All EKM cluster nodes with the same cluster name in a LAN will form
a cluster together. EKM cluster nodes operate cooperatively and transparently as a single EKM server. In
order to deploy more than one EKM server in clustered configuration on a LAN, the cluster name of each
EKM server MUST be unique within the LAN. The cluster name is specified during product installation when
the cluster node is installed.
2. Each EKM cluster node has a node name (also referred to as node ID). The node name is specified during
product installation when the cluster node is installed. Within a cluster, all node names MUST be unique.
The combination of cluster name and node name uniquely identifies each cluster node.
Consider the following scenario: two EKM servers are deployed on the same LAN. The first EKM server
has cluster name: EkmServer1. The second EKM server has cluster name: EkmServer2. EkmServer1 has
three cluster nodes: node1, node2 and node3. EkmServer2 has two cluster nodes: node1 and node2.
Both clusters have cluster nodes named node1 and node2, but these cluster nodes belong to different
EKM servers because they use different cluster names.
Important
EKM uses JGroups and Infinispan clustering software to provide EKM cluster services. It is
not necessary under normal circumstances to change the configuration of these components.
For more information, see Appendix Q: EKM Cluster Network Configuration (p. 145).
Chapter 5: Installing an EKM Server
This chapter describes how to install and set up an EKM server. We recommend that you follow the
specific steps outlined in Steps for Setting Up an EKM Server (p. 8) before continuing. Otherwise, you
may encounter errors or unpredictable behavior during the server setup process.
Important
All of the examples provided in this chapter are for Windows systems. Follow the same
process for EKM servers that are set up on Linux systems but substitute Linux file system
paths for the Windows paths shown here.
In this chapter:
5.1. Installing a New EKM Server
5.2. Running a Silent Installation
5.3. Special Instructions for Upgrade
5.1. Installing a New EKM Server

This section presents instructions for setting up a new EKM server using the ANSYS EKM Server product
installation. If you are setting up a new server as part of an upgrade, refer to Special Instructions for
Upgrade (p. 35) before proceeding with the steps in this section.
5.1.1. Installation Requirements

An EKM server requires one or more EKM cluster nodes, and a cluster database server. During installation
you will set up a cluster database server and one or more cluster nodes.
Cluster nodes are set up one at a time using the ANSYS EKM Server product installation. Cluster nodes
must meet the following requirements:
• It is required that all cluster nodes be set up on the same operating system architecture (Windows or Linux).
• It is required that one (and only one) cluster node in the cluster be designated as the EKM cluster primary
node.
When installing more than one cluster node on the same server host, the following additional require-
ments apply:
• It is required that each cluster node on the same server host use a different JBoss port offset.
To set up a cluster node, follow the instructions in Running ANSYS EKM Server Product Installation (p. 31),
observing the following special instructions:
When setting up a cluster node, the Database Server Type step applies to the cluster database server:
Installing an EKM Server
• Set up the default database server: MySQL: Choose this to set up the default MySQL database server as
the cluster database server.
• Use an existing database server: Choose this to specify the connection information for an existing cluster
database server.
Although the product installation will prompt you to enter these settings, these guidelines will help
you understand them ahead of time:
1. The cluster name identifies the cluster that the cluster node will be a member of.
2. The cluster node name identifies the name of the cluster node within the cluster. Specify a unique cluster
node name (also referred to as “cluster node ID”) for each cluster node.
3. One cluster node must be designated as the primary node. This will usually be the first cluster node you
install.
4. When installing a non-primary node, provide the IP address of the primary cluster node.
5. If multiple cluster nodes are installed on the same server host, specify a unique JBoss port offset for each
cluster node.
6. The base directory for the EKM server must be a located on a file share on the cluster file server—this dir-
ectory will be accessed by all cluster nodes.
7. The base directory for the EKM cluster node must be unique for each cluster node. This directory can be
located on local storage on the server host, or on a file share on the cluster file server.
8. The shared path for the EKM data directory must be located on a file share on the cluster file server—this
directory will be accessed by all cluster nodes.
9. The EKM job data directory must be located on a file share on the cluster file server—this directory will be
accessed by all cluster nodes.
10. When configuring the EKM database server, specify the connection information needed to connect to the
cluster database server.
Important
When configuring the EKM database server, provide one of the following valid values for the
hostname:
• The Fully-Qualified Domain Name (FQDN) of the cluster database server, such as ekmCluster-
Db.yourdomain.com
• The network-accessible IP address of the cluster database server, such as 192.168.1.2
An invalid value will result in an inoperable cluster. Examples of invalid values include:
• localhost
• Any IP address that is not network accessible, such as 127.0.0.1
• Any hostname that is not fully-qualified, such as ekmClusterDb
Installing a New EKM Server
Each cluster node MUST be provided with identical EKM database server configuration. These
requirements apply to all cluster nodes, including those installed on the same host as the
cluster database server.
5.1.2. Running ANSYS EKM Server Product Installation
Important
• The ANSYS EKM Server product installation must be executed by the EKM server account in order
to ensure that the EKM server account has correct access permissions to all files created during
installation.
• On Windows, EKM does not support mapped drives when run as a Windows service. If you will
be running EKM as a Windows service, all paths provided in the Setup wizard must be UNC paths
or paths to local filesystems.
An information icon appears next to various settings throughout the ANSYS EKM Server product
installation. Hovering over this icon displays a tooltip that provides information about that setting.
To install an EKM server, follow these instructions:
1. Save all data and close all Windows applications before continuing.
2. Execute the setup.exe program in the product installation directory to start the installation launcher.
3. Select Install ANSYS EKM Server.
To execute the ANSYS EKM Server product installation on Linux systems, run the INSTALL.EKMSVR
program in the product installation directory:
/<mount_dir>/INSTALL.EKMSVR
You must install ANSYS Workbench and any other desired components before installing the EKM
Server.
4. Read the terms of the license agreement, and if you agree, select I Agree. You must agree to the terms
to continue with the installation.
5. On the Prerequisites screen, review the machine prerequisites (p. 15) and perform the necessary pre-
requisite operations (p. 19). Once all of the prerequisites are fulfilled, check the Prerequisites fulfilled
box and continue to the next screen.
6. On the Cluster Node Settings screen, specify whether the node that you are defining is the Primary
node or a Non-Primary node in the EKM cluster.
• If you are defining the Primary node, specify the following settings:
EKM cluster name: The name of the EKM cluster to which the cluster node belongs. The
default is ekmserver.
EKM cluster node ID: The node ID for the node in the EKM cluster. The default is node1.
JBoss port offset: The JBoss port offset for the EKM server. The default value is 0. For more
information, see Appendix E: Resolving Network Port Conflicts (p. 129).
• If you are defining a Non-Primary node, specify the following settings:
EKM cluster node ID: The node ID for the node in the EKM cluster. The default is node1.
EKM cluster primary node IP address: The IP address of the primary cluster node of the
EKM cluster.
JBoss port offset: The JBoss port offset for the EKM server. The default value is 0. For more
information, see Appendix E: Resolving Network Port Conflicts (p. 129).
7. On the Database Server Type screen, select one of the following:
• Set up the default database server: MySQL: Use the MySQL database server that is bundled with
EKM.
• Use an existing database server: Use a database server that is already set up for EKM. Select either
MySQL or Oracle in the drop-down list to specify the existing database server type.
8. Specify the Database Server Settings:
• If using the default MySQL database server:
EKM database directory: The base directory for the cluster database server installation (The
default is C:\ekm\mysql-5.5.41).
Port number: The port number that will be used to connect to the cluster database server
(the default is 3306).
Password: The password that will be used to connect to the cluster database server.
• If using an existing database server:
Host name: The name of the host where the cluster database server is running (the default
is localhost).
Port number: The port number that will be used to connect to the cluster database server
(the default is 3306 for MySQL and 1521 for Oracle).
User name: The user name that will be used to connect to the database server (for example,
root).
Password: The password that will be used to connect to the cluster database server.
Database name: The name of the database created for EKM (for example, ekm).
(Oracle only) JDBC database driver location: The location of the Java Database Connectivity
(JDBC) driver that you downloaded from the database software vendor site. See Download
the JDBC Driver for the Cluster Database Server (p. 19).
Note
If the JDBC driver consists of more than one file, you must provide the location of all
of the JDBC driver files. These should be entered as a comma-separated list containing
the full path and filename of each JDBC driver file. You can multi-select JDBC driver
Installing a New EKM Server
files in the file selector by clicking the Browse button, and then holding down the
CTRL key while selecting multiple files.
9. On the Setup Directories screen, specify the following settings:
• Base directory for the EKM server: The directory where EKM and the server environment will be set
up (for example, \\server\share\ekm). The base directory cannot contain spaces. This directory
must be a located on a file share on the cluster file server. This directory will be accessed by all EKM
cluster nodes.
• Base directory for the cluster node: The directory where the cluster node will be set up (for example,
C:\ekm\node1). The base directory cannot contain spaces.
• Shared path for the EKM data directory: The internal storage directory for files stored in the EKM re-
pository (for example, \\server\share\ekm\datastore). This directory must be a located on a
file share on the cluster file server. This directory will be accessed by all EKM cluster nodes.
• EKM job data directory: The directory on the RSM Manager machine where EKM job data is staged.
This directory must exist prior to installation, and must be the same as the shared cluster directory
specified in RSM. This directory must be visible to all cluster compute nodes. For information about how
to specify this directory, see the jobSourceRootPath setting in the Administration Guide. This dir-
ectory must be a located on a file share on the cluster file server. This directory will be accessed by all
EKM cluster nodes.
• EKM cluster visible directories: Top-level paths that are visible to all compute cluster nodes. Only
locations within these paths will be allowed as working directories for jobs.
You do not need to include the EKM job data directory here, as EKM automatically considers it
to be visible.
You only need to specify this setting if you are using a relative path for a Linux installation.
See the clusterVisibleDirectories setting in the Administration Guide.
• EKM temp directory: The directory used by EKM to store temporary files. It must be writable by the
EKM server account. (p. viii)
• ANSYS licensing directory: The directory where ANSYS licensing is installed.
10. On the EKM Server Account Settings screen, specify the following settings:
• Windows Domain (for example, mycompany.com) (Windows only): The Windows domain of the EKM
server account. To use a local user account that does not belong to a domain, leave the field blank.
• Name (for example, johndoe) (Windows only): The user name for the EKM server account. The user
account is either an Active Directory user account, or a local user account.
• Designated root user. The Root User is the primary administrator for an EKM workspace, and is the
only user who can perform restricted workspace configuration. The user specified in this setting will
be the default Root User for all workspaces defined in EKM. When a workspace is initialized, a user account
will be automatically created for this user. To specify the Root User, enter that user’s EKM user name.
Note that this user must have a valid OS or LDAP account to be able to log into EKM. For more inform-
ation on how EKM user names are determined, see How User Logins Work (p. 72).
Note that you can change the Root User later by editing the defaultRootUser setting in the
ekm.xml file. See Specifying General Server Settings in the Administration Guide for details.
• Session timeout (in minutes): The amount of idle time before the EKM server will automatically log
you out. Default is 30 minutes.
• Host name of the SMTP (mail) server (for example, smtp.mycompany.com): The host name of the
SMTP mail server that EKM will use to send email.
• RSM Windows Domain: Specify this setting if EKM will be integrating with an RSM Manager running
on Windows. This is the Windows domain name that will be prepended to the user name of all EKM
users when batch jobs are submitted to RSM. For more information, see the rsmWindowsDomain
(Windows only) setting in the Administration Guide.
11. Continue to the next screen to begin installing files.
12. Once the installation is complete, specify whether or not you wish to participate in the installation survey
by enabling or disabling the Launch survey upon exiting check box. Click Exit.
ANSYS EKM Server product installation generates a log file named install.log in the cluster node
base directory that records details about the setup process, including any errors that were encountered.
Repeat the ANSYS EKM Server product installation to install additional cluster nodes, as required.
5.2. Running a Silent Installation

The general form to run a silent product installation on Windows systems from the Start > Run menu
or from the command line is:
setupEKMSVR.exe -silent
The general form to run a silent product installation on Linux systems from the command line is:
INSTALL.EKMSVR -silent
You can use the following arguments when running a silent installation:
-silent Initiates a silent installation.

-help Displays a list of valid arguments for a silent installation.
-ekm_prop Specifies the location of the Java properties file that contains the installation
options.
In order to perform a silent installation, you must create a silent installation file. This file is described
in Appendix P: Creating a Silent Installation File (p. 139).
ANSYS EKM Server product installation generates a log file named install.log in the cluster node
base directory that records details about the setup process, including any errors that were encountered.
Special Instructions for Upgrade
5.3. Special Instructions for Upgrade

To set up a new EKM server as part of an upgrade from a previous version, you must follow the same
procedure for Installing a New EKM Server (p. 29) while observing these special instructions during
the installation process:
Important
Failure to adhere to these special instructions during server setup will result in an upgrade
failure during execution of the EKM upgrade wizard.
1. When specifying the Shared path for the EKM data directory, recall that this path must be located on
a file share on the cluster file server.
If the EKM data directory for EKM 16.0 already meets this requirement, specify the same directory
for EKM 17.0.
If the EKM data directory for EKM 16.0 does not meet this requirement, for example if it is a local
filesystem path, you must specify a new location for the EKM data directory for EKM 17.0. After
installation, you must manually copy or move the data from the EKM 16.0 data directory to the
new EKM 17.0 data directory before running the EKM Upgrade wizard.
2. When specifying the EKM job data directory (jobSourceRootPath), set the value in EKM 17.0 to the
same value set in EKM 16.0.
Doing this will allow seamless access to job data for jobs run in 16.0. If you need to use a new path
for the EKM job data directory and cannot follow these instructions, then you will need to manually
copy or move your 16.0 job data files into the new directory structure. This could be done before
or after the upgrade, but should be done before you start the newly upgraded EKM 17.0 server for
the first time.
For information about setting up the job data directory, see the jobSourceRootPath and
clusterVisibleDirectories settings in Specifying Remote Process Policies (<remoteProcess>)
in the Administration Guide.
3. If the existing EKM 16.0 server is a Production server and uses an external database, or the new EKM 17.0
server uses an external database, then the values you will enter on the Database Server Settings screen
will depend on the approach you choose for preparing your database for upgrade. See Prepare the EKM
Database for an Upgrade – Part 1 (p. 103) for more information.
Important
After installing EKM 17.0 as part of an upgrade, do not start the EKM 17.0 server until
instructed to do so.
There are also post-setup steps that are specific to upgrades. See Special Post-Setup Instructions for
Upgrade (p. 41) for details.
Chapter 6: Post-setup
In order to complete the setup of an EKM server, some requirements must be satisfied after setup is
completed. You will be prompted to review and fulfill these requirements in the Post-Setup step in
the ANSYS EKM Server product installation (p. 29) before you can finish.
This chapter describes:

6.1. Post-Setup Instructions
6.2. Configure the MySQL Connector/J JDBC Driver (Optional)
6.3. Grant Database Privileges for Each Cluster Node on the Cluster Database Server
6.4. Manually Configure the JBoss Domain
6.5. Deploy the EKM Server Application to the Application Server
6.6. Manually Configure the Front-End Web Server
6.7. Special Post-Setup Instructions for Upgrade
6.8. After Installation and Post-setup
If you are setting up a new server as part of an upgrade, read Special Post-Setup Instructions for Up-
grade (p. 41) before proceeding with the steps in this section.
6.1. Post-Setup Instructions

Perform the following steps for a new server setup, and when prompted in ANSYS EKM Server product
installation, indicate that they have been fulfilled by checking the box in the Post-Setup step.
Complete the following post-setup steps:
1. Configure the EKM Server (p. 37)
2. Set the Location of ANSYS 17.0 Applications (p. 38)
3. Set Up an X Server (Linux) (p. 38)
6.1.1. Configure the EKM Server

Complete this step before starting EKM for the first time. This step is performed on the primary cluster
node only.
The configuration file EKM_HOME/conf/ekm.xml contains EKM configuration settings that you can
change. You may want to verify your configuration settings following the EKM server installation.
To configure the EKM server, follow these steps on the primary cluster node:
• If necessary, change the ekmUrl setting in the ekm.xml file to the URL of the EKM server or the URL of
the front-end web server. Refer to the ekmUrl setting in the Specifying General Server Settings section in
the Administration Guide for details.
• Verify that the EKM job data directory (specified during installation, and captured in the jobSourceRoot-
Path setting in the ekm.xml file) is visible on the RSM Manager machine.
Post-setup
• In the ekm.xml file, configure the clusterVisibleDirectories setting to specify directories that
are visible to compute cluster nodes. You can create entries for multiple directories if necessary. Ensure that
the jobSourceRootPath setting (the job data directory) is set to or resides under one of the directories
specified in the clusterVisibleDirectories setting, and that all users who will be submitting jobs
have permission to read/write to this directory. For details refer to these settings in the Specifying Remote
Process Policies (<remoteProcess>) section in the Administration Guide.
Important
If you specify an absolute path for the jobSourceRootPath setting, it is recommended

that you create a directory under the job data directory which has the same name as your
default workspace (or whatever workspace users will be submitting jobs from), and ensure
that every user who will be submitting jobs in this workspace has permission to read/write
to this workspace directory. For more information, see EKM and RSM Job Directories in
the Administration Guide.
6.1.2. Set the Location of ANSYS 17.0 Applications

Complete this step before starting EKM for the first time. This step includes instructions for the primary
cluster node, and for all cluster nodes.
EKM comes with a set of predefined application definitions in the directory: EKM_HOME/conf/applic-
ations. These include definitions for ANSYS 17.0 applications. The definitions for ANSYS 17.0 applications
refer to the environment variable AWP_ROOT170, which provides the location where ANSYS 17.0 ap-
plications are installed.
1. On the primary cluster node, set the AWP_ROOT170 environment variable (shown in bold) in
EKM_ROOT170/bin/ekm_env.(cmd|sh) to the base directory where ANSYS 17.0 applications are
installed. This environment variable is commented out; remove the comment and set it to the correct
location.
Linux:
# Path to ANSYS Installation
export AWP_ROOT170=/server/ansys_inc/v170
Windows:
rem Path to ANSYS Installation
set AWP_ROOT170=\\server\ansys_inc\v170
2. (Windows only) On each cluster node, set the AWP_ROOT170 environment variable (shown in bold) in
JBOSS_HOME/domain/configuration/wrapper.conf:
set.AWP_ROOT170=\\server\ansys_inc\v170
For more information about predefined application definitions, refer to Predefined External Applications.
6.1.3. Set Up an X Server (Linux)

node only.
Configure the MySQL Connector/J JDBC Driver (Optional)
When EKM is set up on Linux, an X server is required by EKM in order to perform various tasks, including
metadata and report extraction.
The X server must be configured to allow connections from the EKM server.
To set up EKM to use an X server on Linux, perform the following steps. These steps are required for an
EKM server running on Linux:
1. Configure an X server for use by EKM. An X server can be configured to allow connections from EKM in a
variety of ways, including:
• Granting host-based access to the EKM server host using xhost.
• Granting user-based access to the EKM server account used to run EKM using xauth.
• Disabling access control to the X server by executing the X server with a special argument (-ac on
some X servers).
Important
The X server for EKM must be a real X server with a hardware frame buffer, or a VNC
server. Virtual X servers such as Xvfb are not fully compatible with EKM.
It is also important that the X server used by EKM remains unlocked, as locking the
screen can cause certain tasks to fail.
The X server for EKM should be configured to run as a service (controlled by the init subsystem),
following the model used by your Linux distribution. Consult with your IT department for assistance
in configuring an X server for use with EKM.
2. On the primary cluster node, edit EKM_ROOT170/bin/ekm_env.sh to set the DISPLAY environment
variable (shown in bold) to the X server configured in step 1. This environment variable is commented
out; remove the comment and set it to the correct value.
# X11 DISPLAY
export DISPLAY=localhost:0
In the example above, DISPLAY is set to a local X display :0 on the local system. It is also possible
to set DISPLAY to a remote X server running on another host. The X server must be configured
to allow access by EKM in either case.
6.2. Configure the MySQL Connector/J JDBC Driver (Optional)

When MySQL is selected as the database server during ANSYS EKM Server product installation, the
MySQL-compatible MariaDB Connector/J driver is installed by default. This is a freely distributable driver
that is compatible with MySQL. It is not the same as MySQL Connector/J.
For production usage of EKM, it is recommended that you download and configure the MySQL Connect-
or/J driver.
Post-setup
To configure the MySQL Connector/J JDBC driver, follow the instructions in Appendix R: Configuring
the MySQL Connector/J JDBC Driver (p. 146).
6.3. Grant Database Privileges for Each Cluster Node on the Cluster
Database Server
Complete this step before starting EKM for the first time. This step includes instructions for the cluster
database server.
These instructions apply if the EKM 17.0 server uses the default MySQL database server installed by
ANSYS EKM Server product installation for EKM 17.0, or when upgrading from an earlier version of EKM.
Each EKM cluster node requires database privileges on the cluster database server in order to access
and modify the EKM database. For instructions on granting database privileges on a MySQL database
server, refer to Appendix K: Granting Database Privileges (p. 135). Follow the instructions to grant database
privileges to the EKM database for each EKM cluster node.
For instructions on granting database privileges on an Oracle database server, consult the Oracle database
server documentation.
6.4. Manually Configure the JBoss Domain

An EKM cluster includes one or more EKM cluster nodes. These EKM cluster nodes use JBoss in domain
mode (p. 121). The ANSYS EKM Server product installation installs JBoss as part of the EKM server envir-
onment and configures it for domain mode operation.
After product installation is completed for all cluster nodes, complete manual configuration of the JBoss
domain to allow each non-primary cluster node to register with the primary cluster node. To complete
this step, refer to Appendix C: JBoss Domain Mode and Configuration (p. 120) and follow the steps to
Create JBoss Management Users (p. 122).
6.5. Deploy the EKM Server Application to the Application Server

node only.
In order to run the EKM server application, it is necessary to manually deploy the EKM server application
to the application server.
1. (Upgrade Only) If you are performing post-setup for a new EKM server as part of an upgrade, perform this
step first.
In the new EKM server, edit the configuration file EKM_HOME/conf/ekm.xml. Find the modules
element and disable ekmServer module by setting the value of the enabled attribute to false:
<modules>
<module name="ekmServer" enabled="false" />
</modules>
2. Manually deploy the EKM server application to the application server by following the steps in Appendix
C: JBoss Domain Mode and Configuration (p. 120).
Special Post-Setup Instructions for Upgrade
6.6. Manually Configure the Front-End Web Server

Complete this step before starting EKM for the first time. This step includes instructions for the front-end
web server.
A front-end web server is optional for a single-node EKM server, and is required for a multi-node EKM
server. Complete instructions for installing and configuring a front-end web server for use with EKM
are provided in Installing a Front-End Web Server (p. 43).
6.7. Special Post-Setup Instructions for Upgrade

To perform post-setup for a new EKM server as part of an upgrade from a previous version, follow the
same procedure for Post-Setup (p. 37), and in addition follow these special instructions during the
post-setup process:
1. Transfer Custom Settings and Plug-ins (p. 41)
2. Rename User Accounts (p. 41)
Transfer Custom Settings and Plug-ins

node only.
1. In the new EKM server, edit the configuration file EKM_HOME/conf/ekm.xml, and manually transfer
any custom settings to this configuration file from the old EKM server. Be aware that there are differences
in format and content between the old and new versions of ekm.xml, but many settings in the old version
are present in the new version, and therefore can be manually transferred as appropriate. Do not replace
the new ekm.xml with the old one.
2. Copy any custom plug-ins from the plugins-deploy directory of the old EKM server to the plugins-
deploy directory of the new EKM server. Custom plug-ins must be validated for compatibility with the
new EKM version; if this has not been done, do not copy them to the new EKM server at this time.
Important
Do not start the new EKM server until instructed to do so. The EKM server application is de-
ployed to the application server, but remains disabled until ready to run the Upgrade wizard
to upgrade EKM.
Rename User Accounts

Complete this step after starting EKM for the first time.
If in the previous version of EKM there were user accounts that differed only by case (for example, js-
mith, jSmith, and JSMITH), you must rename the duplicate accounts. EKM 17.0 will not allow multiple
user accounts that differ only by case.
To rename a user account:
1. Sign in to EKM and go to the Administration/Users page.
2. Right-click the user name and select Edit > Rename.
Post-setup
6.8. After Installation and Post-setup
Important
If performing post-setup for a new EKM server as part of an upgrade from a previous version,
do not complete these steps until after running the Upgrade wizard.
After installation and post-setup, some of the tasks that you may need to perform include:
• Configuring Job Submission Queues (p. 42)
• Configuring Login Authentication and Access Settings (p. 65)
• (for interactive jobs) Installing and Configuring EnginFrame (p. 79)
The Administration Guide covers additional configuration tasks that can be performed in EKM. Some of
the key tasks may include:
• Setting Up Users and Groups
• Creating and Managing Workspaces
• Defining Custom Types
• Integrating EKM with Remote Solve Manager (RSM)
• Defining EKM Servers, Queues, and External Applications
• Defining and Configuring Lifecycles
6.8.1. Configuring Job Submission Queues

Complete this step after starting EKM for the first time.
Load or add application definitions in job submission queues. When you start EKM for the first time,
job submission queues will automatically be synchronized with those defined in RSM, but you still must
populate those queues with application definitions. After you have started the EKM server, refer to De-
fining Job Submission Queue Settings in the Engineering Knowledge Manager for more information.
Chapter 7: Installing a Front-End Web Server
An EKM server consists of one or more EKM cluster nodes. On each EKM cluster node, the EKM server
application is installed in an application server. The application server handles requests from clients
such as web browsers, and forwards them to the EKM server application for processing. In this scenario,
the client is making requests directly to the application server(s) where EKM is installed and set up. This
is the default configuration installed by the ANSYS EKM Server product installation. This configuration
is suitable for most single-node EKM servers. For a multi-node EKM server, an additional component
called the “front-end web server” is required.
A front-end web server is a web server that is deployed between the client and the EKM cluster node(s).
The web server is configured to recognize requests for certain URLs, and forward those requests trans-
parently to the application server(s) on the EKM cluster node(s). This web server is referred to as a front-
end web server because, from the perspective of a client, it is in front of the application server(s) hosting
the EKM server application. EKM supports the use of Apache HTTP Server as a front-end web server.
This arrangement can be used to “virtualize” the URL that clients use to connect to EKM. The client always
uses the same URL to get to the EKM server while the EKM cluster nodes can have any name/location.
This arrangement provides flexibility to IT professionals who deploy and maintain the EKM server.
A front-end web server provides the ability to load balance connections in a multi-node EKM server,
providing better user experience and resource management.
The use of a front-end web server also provides a way to expose an EKM server to the internet (such
as on a protected DMZ network), while keeping back-end services like the file server and database
server on a protected LAN.
Depending on your security needs, the front-end web server can be configured to support encryption
via HTTPS, and can employ various authentication and access-control mechanisms that the web server
supports. A complete discussion of web-server configuration is beyond the scope of this document,
but instructions are provided for enabling HTTPS on the Apache web server.
Use of a front-end web server is optional when setting up an EKM server in a single-node configuration,
and is required in a multi-node configuration. Instructions specific to either single-node or multi-node
configuration will be highlighted in the instructions that follow. The front-end web server is installed
manually, and not by the ANSYS EKM Server product installation.
7.1. The Architecture of an EKM Server

The architecture of an EKM server with a front-end web server is shown in Figure 7.1: Communication
for EKM with Front-End Web Server (p. 44). In this diagram, the EKM server is depicted in a multi-node
configuration. For a single-node configuration, the same communication architecture is used, the only
difference being that the front-end web server communicates with a single EKM cluster node.
Installing a Front-End Web Server
Figure 7.1: Communication for EKM with Front-End Web Server
The steps for configuring EKM with a front-end web server, outlined below, comprise the remainder of
this chapter:
1. Installing the Web Server and Load Balancer (p. 44)
2. Configuring the Web Server and Load Balancer (p. 46)
3. Configuring the Application Server (p. 49)
4. Configuring EKM to communicate with the web server (p. 51)
5. Testing the connection (p. 51)
6. Enabling HTTP compression (p. 52)
7. Enabling secure connections to the web server (p. 54) (Optional)
8. Securely connecting to EKM (p. 62) (Optional)
7.2. Installing the Web Server and Load Balancer

A front-end web server fields incoming requests from clients. In order to pass these requests to EKM
and receive responses, the web server must be equipped and configured to communicate with the
application server(s) hosting the EKM server application. A load balancer is used to communicate between
the web server and the application server(s).
Installing the Web Server and Load Balancer
This section documents the steps for installing and configuring Apache web server and mod_cluster
load balancer for use with EKM.
7.2.1. Using EKM with Apache HTTP Server and mod_cluster

Apache HTTP Server ("Apache") can be used as the front-end web server for a single-node or multi-node
EKM server. When using Apache as the front-end web server, a load balancer called mod_cluster is used
to communicate between the web server and the application server(s) on the EKM cluster node(s). The
combination of Apache, mod_cluster, and JBoss application server is referred to in this guide as:
JBoss/Apache/mod_cluster.
Table 7.1: Example Configuration - Apache (p. 45) shows an example configuration for a multi-node
EKM server with an Apache front-end web server. Host A is the web server, while Host B and Host C
are the EKM cluster nodes.
Table 7.1: Example Configuration - Apache
Host A: front-end web server Host B: EKM node 1 Host C: EKM node 2
Hostname: ekm.yourdomain.com ekm1.yourdomain.com ekm2.yourdomain.com
IP Address: 192.168.1.2 192.168.1.3 192.168.1.4
Software: Apache HTTP server EKM (includes JBoss) EKM (includes JBoss)
The following software is needed on Host A (front-web server), depending on the version of Apache
that is used. Apache v2.4.x is recommended:
Apache v2.4.x:
• Apache HTTP server (with OpenSSL) v2.4.1 or higher
• mod_cluster v1.3.1 or higher
Apache v2.2.x:
• Apache HTTP server (with OpenSSL) v2.2.8 or higher
• mod_cluster v1.2.6
There are a number of options available for installing Apache and mod_cluster:
• Most Linux distributions provide Apache and mod_cluster among the packages that can be installed from
the installation media or online package repositories.
• mod_cluster binary distributions are available from the mod_cluster project web homepage (http://mod-
cluster.jboss.org) that combine mod_cluster, Apache and OpenSSL in one convenient package.
• Apache is available in binary and source distributions. If you choose to build Apache from source, you must
enable loadable module support. See the Apache documentation for more information about building
Apache from source.
• mod_cluster is available in binary and source distributions. See the mod_cluster documentation for more
information about building mod_cluster from source.
To use EKM with Apache HTTP server and mod_cluster:
1. Install Apache and mod_cluster on the host that will function as the front-end web server.
Note
When referring to paths within the Apache directory structure, the traditional “Apache” dir-
ectory layout is used. If you use a different directory layout, you will need to modify the in-
structions in this section accordingly. See the Apache documentation for details about direct-
ory layouts.
7.3. Configuring the Web Server and Load Balancer

The front-end web server communicates with the application server(s) on the EKM cluster node(s) using
the mod_cluster load balancer. This load balancer forwards requests from the web server to the applic-
ation server(s) (Figure 7.1: Communication for EKM with Front-End Web Server (p. 44)). In a multi-node
EKM server, mod_cluster also provides load balancing of client connections to the cluster nodes.
mod_cluster handles the communications between the front-end web server and application server(s).
mod_cluster can be configured to use HTTP, HTTPS or AJP. This chapter provides instructions for con-
figuring mod_cluster for use with HTTP or AJP. To configure mod_cluster for use with HTTPS, please
consult the mod_cluster documentation.
Note that the communications between the client and the front-end webserver are not impacted by
the choice of communication protocol for mod_cluster. For example, a client such as a web browser
may communicate with the front-end web server using HTTPS, while the front-end web server (via
mod_cluster) communicates with the application server(s) on the EKM cluster node(s) using another
protocol such as HTTP or AJP.
7.3.1. mod_cluster (Apache)

mod_cluster is implemented as a set of Apache modules. mod_cluster allows the front-end Apache
web server to communicate with the JBoss application server(s) that host the EKM server application.
To configure Apache + mod_cluster, perform the following steps. Depending on the installation option
you chose, some of these steps may require configuration changes, or they may only require verification
of the existing configuration:
1. In the directory: APACHE_HOME/modules, the following modules must be installed:
Apache v2.4.x:
• mod_cluster_slotmem.so
• mod_manager.so
• mod_proxy_cluster.so
• mod_advertise.so
Apache v2.2.x:
• mod_slotmem.so
• mod_manager.so
Configuring the Web Server and Load Balancer
• mod_proxy_cluster.so
• mod_advertise.so
2. Configure, or verify the configuration of the mod_cluster and related modules in the Apache configuration
file.
In the Apache configuration file APACHE_HOME/conf/httpd.conf, configure, or verify the

configuration of the following modules:
Apache v2.4.x:
LoadModule proxy_module modules/mod_proxy.so
LoadModule proxy_ajp_module modules/mod_proxy_ajp.so
LoadModule proxy_http_module modules/mod_proxy_http.so
LoadModule cluster_slotmem_module modules/mod_cluster_slotmem.so
LoadModule manager_module modules/mod_manager.so
LoadModule proxy_cluster_module modules/mod_proxy_cluster.so
LoadModule advertise_module modules/mod_advertise.so
Apache v2.2.x:
LoadModule proxy_module modules/mod_proxy.so
LoadModule proxy_ajp_module modules/mod_proxy_ajp.so
LoadModule proxy_http_module modules/mod_proxy_http.so
LoadModule slotmem_module modules/mod_slotmem.so
LoadModule manager_module modules/mod_manager.so
LoadModule proxy_cluster_module modules/mod_proxy_cluster.so
LoadModule advertise_module modules/mod_advertise.so
The path to the modules may be different, depending on your Apache installation.
3. Configure, or verify the configuration of Apache.
In the Apache configuration file: APACHE_HOME/conf/httpd.conf
a. Configure the Listen directive to control which IP address(es) and port(s) the web server will listen
on:
Listen 80
b. Configure the VirtualHost, or create a new VirtualHost to handle connections to the front-end web-
server on the desired port. For example:
<VirtualHost 192.168.1.2:80>
ServerName ekm.yourdomain.com
</VirtualHost>
4. Configure, or verify the configuration of mod_proxy.
In the Apache configuration file: APACHE_HOME/conf/httpd.conf, configure the ProxyPre-

serveHost directive:
ProxyPreserveHost on
5. Configure, or verify the configuration of the mod_cluster manager. The mod_cluster manager provides
a web interface for managing mod_cluster.
In the Apache configuration file: APACHE_HOME/conf/httpd.conf, configure the mod_cluster

manager. Change the IP address settings (shown in bold) to match your configuration:
Apache v2.4.x:
<IfModule manager_module>
Listen 192.168.1.2:6666
ManagerBalancerName mycluster
<VirtualHost 192.168.1.2:6666>
<Location />
Require ip 192.168.1.2
</Location>
KeepAliveTimeout 300
MaxKeepAliveRequests 0
#ServerAdvertise on http://192.168.1.2:6666
AdvertiseFrequency 5
#AdvertiseSecurityKey secret
#AdvertiseGroup 224.0.1.105:23364
EnableMCPMReceive
<Location /mod_cluster_manager>
SetHandler mod_cluster-manager
Require ip 192.168.1
</Location>
</VirtualHost>
</IfModule>
Apache v2.2.x:
<IfModule manager_module>
Listen 192.168.1.2:6666
ManagerBalancerName mycluster
<VirtualHost 192.168.1.2:6666>
<Location />
Order deny,allow
Deny from all
Allow from 192.168.1.2
</Location>
KeepAliveTimeout 300
MaxKeepAliveRequests 0
#ServerAdvertise on http://192.168.1.2:6666
AdvertiseFrequency 5
#AdvertiseSecurityKey secret
#AdvertiseGroup 224.0.1.105:23364
EnableMCPMReceive
<Location /mod_cluster_manager>
SetHandler mod_cluster-manager
Order deny,allow
Deny from all
Allow from 192.168.1
</Location>
</VirtualHost>
</IfModule>
Note
Some firewalls and security products may process or alter traffic whose destination port is
port 80 (HTTP) in ways that may cause EKM to function incorrectly. If you decide to configure
the EKM server, or a front-end web server, to listen on port 80 and experience difficulties
using the EKM server, it may be necessary to configure the EKM server or front-end web
server to use another port such as 8080.
Configuring the Application Server
7.4. Configuring the Application Server

The previous sections in this chapter have covered installing and configuring the web server and load
balancer, from the perspective of the front-end web server. Recall that the load balancer enables the
communication between the front-end web server and the application server(s) on the EKM cluster
node(s).
The JBoss application server installed with each EKM cluster node is configured by default to commu-
nicate with the front-end web server via the mod_cluster load balancer using the AJP protocol, with
no further configuration required. To change the configuration of the JBoss application server, refer to
the steps in this section.
7.4.1. JBoss Setup

The JBoss application server may need to be configured to match the settings of the Apache web
server and mod_cluster load balancer, depending on the settings you chose in those components. To
configure JBoss, follow these steps:
7.4.1.1. Configure JBoss mod_cluster
7.4.1.2. Configure JBoss Web Services
7.4.1.3. Configure JBoss Undertow (Optional)
7.4.1.1. Configure JBoss mod_cluster

JBoss can be configured to communicate with the front-end web server via the mod_cluster load bal-
ancer using AJP, HTTP or HTTPS protocols. This section provides instructions for configuring JBoss to
communicate via mod_cluster using AJP or HTTP; for instructions on how to configure JBoss to commu-
nicate via mod_cluster using HTTPS, please consult the JBoss and mod_cluster documentation.
To configure JBoss to communicate via mod_cluster using AJP or HTTP, follow these steps:
1. Edit the JBoss configuration (see Appendix C: JBoss Domain Mode and Configuration (p. 120)).
2. Find the modcluster subsystem element, and find its mod-cluster-config child element:
<subsystem xmlns="urn:jboss:domain:modcluster:1.2">
<mod-cluster-config advertise-socket="modcluster" connector="ajp">
3. Find the undertow subsystem element, and find its server child element. Under the server element,
you will see two elements defining “listeners”: http-listener and ajp-listener:
<subsystem xmlns="urn:jboss:domain:undertow:1.2" instance-id="${jboss.server.name}">
<buffer-cache name="default"/>
<server name="default-server">
<http-listener name="default" socket-binding="http" max-post-size="0"/>
<ajp-listener name="ajp" socket-binding="ajp"/>
4. In the mod-cluster-config element (see step 2), set the value of the connector attribute to the
name of the listener (see step 3) you want mod_cluster to use. You must set the value to the value in the
name attribute of the listener. For example, to use the http-listener, you would specify the value:
default. To use the ajp-listener, you would specify the value: ajp.
AJP:
<mod-cluster-config advertise-socket="modcluster" connector="ajp">
HTTP:
<mod-cluster-config advertise-socket="modcluster" connector="default">
5. (Optional) In the mod-cluster-config element (see step 2), a simple-load-provider child

element defines the load balancing behavior of the mod_cluster load balancer. The simple-load-provider
defines a factor of 1, which causes the load balancer to attempt to spread client load evenly across all
nodes in the EKM cluster.
More fine-grained load balancing behavior can be defined by replacing the simple-load-pro-
vider element with one or more dynamic-load-provider elements. Refer to the mod_cluster
documentation for more information about configuring dynamic load balancing.
7.4.1.2. Configure JBoss Web Services

JBoss web services must be configured to match the configuration of the front-end web server. To
configure JBoss web services, follow these steps:
2. Find the webservices subsystem element:

<subsystem xmlns="urn:jboss:domain:webservices:1.2">
3. Configure the following elements: wsdl-host, wsdl-port, and wsdl-secure-port. The values of
these elements must be configured to match the hostname and HTTP and/or HTTPS port of the front-end
web server. These values control how URLs are written in the WSDL contracts of web services that are
provided by EKM.
<wsdl-host>jbossws.undefined.host</wsdl-host>
<wsdl-port>80</wsdl-port>
<wsdl-secure-port>443</wsdl-secure-port>
wsdl-host:
Set the value of this element to the hostname or IP address of the front-end web server. The special
value jbossws.undefined.host is set by default, which substitutes the hostname from the request
when a web service WSDL is accessed. It is usually not necessary to change this value. Alternatively,
you may specify the hostname or IP address of the front-end web server here.
Examples: jbossws.undefined.host, ekm.yourdomain.com, 192.168.1.2
wsdl-port:
Set the value of this element to the HTTP port of the front-end web server. Examples: 80, 8080
wsdl-secure-port:
Set the value of this element to the HTTPS port of the front-end web server. Examples: 443, 8443
7.4.1.3. Configure JBoss Undertow (Optional)

Undertow is the name of the web server subsystem within JBoss. This subsystem listens for incoming
connections on both AJP and HTTP protocols by default. Depending on your desired configuration, you
may want to disable one of these listeners if you are not using it. For example, if mod_cluster will be
using AJP, you may want to disable the HTTP listener, or vice-versa.
Testing the Connection
To disable a listener, follow these steps:
2. Find the undertow element, and find its server child element. Under the server element, you will
see two elements defining “listeners”: http-listener and ajp-listener:
3. To disable a listener, set the enabled attribute on the listener element to false. For example, to disable
the AJP listener:
<ajp-listener name="ajp" socket-binding="ajp" enabled="false"/>
To enable a listener, reverse these steps.
7.5. Configuring EKM to Communicate with the Web Server

The value of the ekmUrl configuration setting in EKM_HOME/conf/ekm.xml must be changed to
the URL of the front-end web server. Connections to the EKM server will now come through the front-
end web server. Refer to the ekmUrl setting in the General Server Settings section in the Administration
Guide for more details.
7.6. Testing the Connection

Now that the front-end web server, load balancer, and application server are set up, it is time to test
connecting to EKM through the front-end web server.
1. Start the EKM server and front-end web server.
2. Try connecting to EKM using the URL of the front-end web server, for example:
http://ekm.yourdomain.com/ekm or http://ekm.yourdomain.com:8080/ekm
where ekm.yourdomain.com is the name of the front-end web server. The exact URL depends
on the hostname + port of the front-end web server. If the HTTP port is 80, it can be omitted from
the URL as shown in the first example URL.
The EKM login window should appear in your browser. You are now accessing EKM through the
front-end web server.
Note
Some firewalls and security products may process or alter traffic whose destination port
is port 80 (HTTP) in ways that may cause EKM to function incorrectly. If you decide to
configure the EKM server or front-end web server to listen on port 80 and you experience
difficulties using the EKM server, it may be necessary to configure the EKM server or
front-end web server to use another port such as 8080.
7.7. Enabling HTTP Compression

Most web servers support HTTP compression, which can greatly reduce the amount of data that is
transmitted between the client and the web server. This improves the responsiveness of the EKM user
interface, and improves performance of file transfers.
EKM has been tested with HTTP Compression enabled in Apache. Follow these instructions in this section
to enable HTTP Compression in Apache.
7.7.1. Apache
HTTP compression in Apache is provided by the module named “mod_deflate”. Enable and configure
mod_deflate as follows to enable HTTP compression:
1. Stop the Apache server.
2. Edit APACHE_HOME/conf/httpd.conf and enable the mod_deflate module, if necessary:
Disabled (commented out):

#LoadModule deflate_module modules/mod_deflate.so
Enabled:
LoadModule deflate_module modules/mod_deflate.so
3. Edit the VirtualHost entry in APACHE_HOME/conf/httpd.conf that was created in the section
mod_cluster (Apache) (p. 46) and add the mod_deflate-related entries, which are shown in bold:
<VirtualHost 192.168.1.2:80>
AddOutputFilterByType DEFLATE text/html text/plain text/xml
DeflateFilterNote Input input_info
DeflateFilterNote Output output_info
DeflateFilterNote Ratio ratio_info
LogFormat '"%r" %{output_info}n/%{input_info}n (%{ratio_info}n%%)' deflate
CustomLog deflate.log deflate
</VirtualHost>
4. Start the Apache server.
7.8. Overview of Client-Web Server Communications

As shown in Figure 7.2: EKM with Front-End Web Server/HTTPS (DMZ Deployment) (p. 53), communica-
tions between the client browser and web server can either be unencrypted (HTTP) or encrypted (HTTPS).
In order to support encrypted connections, the web server must possess a signed Secure Sockets Layer
(SSL)/TLS certificate (commonly referred to as a cert (p. viii)), and be configured to enable encrypted
connections over HTTPS.
Communications between the web server and the application server(s) on the EKM cluster node(s) via
the load balancer are not encrypted when using the AJP or HTTP protocols. If encryption is required
between the web server and the application server, then the load balancer should be configured to
Overview of Client-Web Server Communications
use the HTTPS protocol. Consult the JBoss and mod_cluster documentation for instructions on setting
up mod_cluster for HTTPS.
Figure 7.2: EKM with Front-End Web Server/HTTPS (DMZ Deployment) (p. 53) shows a typical deployment
of EKM using SSL/TLS in an internet-facing scenario.
Figure 7.2: EKM with Front-End Web Server/HTTPS (DMZ Deployment)
7.8.1. SSL/TLS Certificates: Background

In order to support encrypted connections using HTTPS, a web server must possess a signed Secure
Sockets Layer (SSL)/TLS certificate, commonly referred to as a cert (p. viii). A complete discussion of
how HTTPS works is beyond the scope of this document, but the following provides a quick, highly-
simplified overview.
HTTPS is not really a protocol in and of itself, but rather a combination of HTTP on top of SSL/TLS, which
are encryption protocols. SSL/TLS are asymmetric encryption protocols that use mathematically-related
public/private key pairs at each endpoint to encrypt and decrypt messages between communication
partners.
SSL/TLS relies on a Public Key Infrastructure (PKI) in order to establish trust between communication
partners. In this public key infrastructure, trusted third-parties known as Certificate Authorities perform
the role of verifying the identity of entities such as web servers, and digitally signing SSL/TLS certificates
for those entities.
An SSL/TLS certificate for an entity contains the public key of the entity and information about its
identity, and is digitally signed with the private key of the signing Certificate Authority (CA). When a
client web browser connects to a web server and initiates an HTTPS connection, the web server presents
the client browser with its SSL/TLS certificate. Web browsers typically include local copies of the root
(or “signing”) certificates of major Certificate Authorities. The root certificate of the CA contains its
public key, which can be used to validate whether a given certificate has been signed by that CA because
certificate signing is done using the CA’s private key. When a client browser is presented with a web
server’s certificate, the client browser verifies that the certificate was signed by the CA that it claims to
have been signed by. Once the web server’s certificate is authenticated, the client browser can trust
that the web server is who it says it is because rigorous validation of the identity of an entity is central
to the issuing process for SSL/TLS certificates from reputable Certificate Authorities.
Once the certificate is accepted as valid, the client browser can proceed with setting up an encrypted
HTTPS connection with the web server.
7.8.2. Enabling Secure Connections to the Web Server (Optional)

When communications between the client browser and the front-end web server need to travel over
an untrusted network such as the Internet, it is highly advisable to use secure connections between
the client browser and the front-end web server. This section presents instructions for enabling secure
connections to EKM, using the Apache web server.
• Creating an In-House Certificate Authority (p. 54)
• Creating and Installing a Test Certificate (p. 56)
• Generating a Certificate Signing Request (CSR) (p. 57)
• Signing the CSR (p. 58)
• Installing the Certificate on the Web Server (p. 58)
7.8.2.1. Creating an In-House Certificate Authority

SSL/TLS certificates are typically purchased from well-known Certificate Authorities. Using a certificate
from a well-established and widely recognized CA confers several benefits to the web server operator.
These include increased credibility and convenience because the root certificates for popular CAs are
prepackaged into major browsers, eliminating the need to distribute anything to client browsers that
will connect to the web site.
If a web server is to be used solely internally within an organization, then the benefits of using a certi-
ficate from a well-recognized Certificate Authority may not be important. Any valid SSL/TLS certificate
can be used to encrypt traffic between client browser and web server as long as the client browser
accepts the certificate. For internal production use, and certainly for test use, it is often sufficient to
create and use an in-house Certificate Authority that can sign SSL/TLS certificates for these use cases.
A certificate that is signed by the same party that created it is known as a self-signed certificate. When
an internally-generated certificate is signed using an in-house Certificate Authority, then a self-signed
certificate is created. Self-signed certificates are perfectly usable for enabling HTTPS connections to a
web server. However, when a browser encounters a certificate that has been signed by an unknown
certificate authority, it will present the user with a warning, such as the following:
Figure 7.3: Browser Warning: Unknown CA (Firefox)
Once a user accepts the certificate, the HTTPS connection can proceed.
You can create a self-signed SSL/TLS certificate for testing or internal purposes by creating an in-house
Certificate Authority using OpenSSL. Follow the procedure described below. User inputs are highlighted
in bold.
1. Obtain and install OpenSSL distribution for your operating system (OS).
• Linux Binaries: Install from your OS distribution’s installation media or software repository
• Windows Binaries: http://www.slproweb.com/products/Win32OpenSSL.html
• Source Code: http://www.openssl.org/
Once you have installed OpenSSL, you are ready to proceed with the creation of an in-house Cer-
tificate Authority.
Note
Certificates and private keys should be secured against unauthorized access.
2. Create a directory structure for the in-house CA. Be sure to secure these directories appropriately.
Windows Example:
Base directory:
c:\ssl
Directory for CA root certificate and private key:
c:\ssl\CA
Directory for certificates that the CA signs:
c:\ssl\certs
Directory for certificate signing requests (CSRs):
c:\ssl\requests
3. Create a private key for the CA. You will be asked for a passphrase for the CA key. Remember what you
type here.
c:\ssl\CA>openssl genrsa -des3 -out CA.key 1024
Loading 'screen' into random state - done
Generating RSA private key, 1024 bit long modulus
..........................................++++++
...++++++
e is 65537 (0x10001)
Enter pass phrase for CA.key:
Verifying - Enter pass phrase for CA.key:
4. Create a root certificate for the CA.
You will be asked to provide the passphrase for the CA private key, and for details about the CA
that you are creating a new root certificate for. Enter suitable values for your site and server. This
Certificate Authority will only be used for creating test and in-house certificates, so the values you
enter here aren’t of critical importance, but they should be meaningful.
The CA private key will be used later on to sign a Certificate Signing Request (CSR) for the front-
end web server.
C:\ssl\CA>openssl req -new -key CA.key -x509 -days 1895 -out CA.crt
Enter pass phrase for CA.key:
You are about to be asked to enter information that will be incorporated
into your certificate request.
What you are about to enter is what is called a Distinguished Name or a
DN.
There are quite a few fields but you can leave some blank
For some fields there will be a default value,
If you enter '.', the field will be left blank.
-----
Country Name (2 letter code) [AU]:Your Country Code
State or Province Name (full name) [Some-State]:Your State
Locality Name (eg, city) []:Your Locality Name
Organization Name (eg, company) [Internet Widgits Pty Ltd]:Your
Organization Name
Organizational Unit Name (eg, section) []:
Common Name (eg, YOUR name) []:ekm.yourdomain.com
Email Address []:
7.8.2.2. Creating and Installing a Test Certificate

In order to test the capability of connecting to the front-end web server over HTTPS, a self-signed test
SSL/TLS certificate can be installed on the web server and signed by the in-house Certificate Author-
ity (p. 54).
The steps for generating and installing a SSL/TLS certificate are as follows:
1. Generate a CSR (p. 57) (Certificate Signing Request) for the web server.
2. Sign the CSR (p. 58) with the local CA to produce a signed SSL/TLS certificate.
3. Install the signed certificate (p. 58) on the web server.
7.8.2.2.1. Generating a Certificate Signing Request (CSR)

Follow the instructions below to generate a certificate signing request (CSR) on the Apache web server.
User inputs are highlighted in bold.
Apache
1. Create the directory: APACHE_HOME/conf/keystore. The web server’s private key and certificate will
be stored in this directory:
cd APACHE_HOME/conf
mkdir keystore
2. In the APACHE_HOME/conf/keystore directory, generate a private key for the web server:
APACHE_HOME/conf/keystore>openssl genrsa -out server.key 1024
............++++++
................++++++
e is 65537 (0x10001)
The keystore directory will now contain the private key for the Apache server, in the file serv
er.key.
3. In the APACHE_HOME/conf/keystore directory, generate a CSR for the web server. When completed,
the keystore directory will contain the CSR for the Apache server in the file: server.csr:
APACHE_HOME/conf/keystore>openssl req -new -key server.key -out server.csr
What you are about to enter is what is called a Distinguished Name or a DN.
-----
Country Name (2 letter code) [AU]:Your Contry Code
Organization Name (eg, company) [Internet Widgits Pty Ltd]:Your Organization Name
Email Address []:
Please enter the following 'extra' attributes
to be sent with your certificate request
A challenge password []:
An optional company name []:
Note
The Common Name is the host name that is used to connect to the web server. This is
usually the Fully Qualified Domain Name (FQDN) of the server, for example:
ekm.yourdomain.com. A certificate is valid only for the common name it is issued
for; if the name that is used to connect to the web server is changed, then a new certi-
ficate for the new common name will need to be issued.
7.8.2.2.2. Signing the CSR

Follow the instructions below to “sign” a certificate signing request (CSR). User inputs are highlighted
in bold.
1. If necessary, copy the CSR file you created in the previous step (p. 57) into the requests directory of the
in-house Certificate Authority.
2. Sign the Certificate Signing Request using the in-house Certificate Authority:
C:\ssl>openssl x509 -req -days 1825 -in requests\server.csr -CA CA\CA.crt
-CAkey CA\CA.key -CAcreateserial -out certs\server.crt
Signature ok
subject=/CN=ekm.yourdomain.com/OU=none/O=Your Organization Name/L=Your
Locality Name/ST=Your State/C=US
Getting CA Private Key
Enter pass phrase for CA\CA.key:
The self-signed SSL/TLS certificate produced by this command is named server.crt and is located
in the certs directory of the in-house CA. This certificate is now ready to install on your web server.
7.8.2.2.3. Installing the Certificate on the Web Server

Follow the instructions below to install a certificate on the Apache web server. User inputs are highlighted
in bold.
Apache
1. Copy the self-signed certificate to the keystore directory that was created for the web server in a pre-
vious step.
Windows:
copy c:\ssl\certs\server.crt APACHE_HOME\conf\keystore
Linux:
cp ssl/certs/server.crt APACHE_HOME/conf/keystore
2. Configure Apache to enable SSL and use your self-signed certificate. Edit APACHE_HOME/conf/ht-
tpd.conf as follows:
a. Listen on both port 80 (HTTP) and port 443 (HTTPS):

Listen 80
Listen 443
b. Enable the SSL module.

LoadModule ssl_module modules/mod_ssl.so
c. Create a VirtualHost entry to listen on port 443 (HTTPS) on the IP address of your web server. This
VirtualHost has SSL enabled, using the self-signed certificate and private key of the server:
<VirtualHost 192.168.1.2:443>
SSLEngine on
SSLCertificateFile conf/keystore/server.crt
SSLCertificateKeyFile conf/keystore/server.key
</VirtualHost>
3. Restart the web server to pick up the configuration changes.
7.8.3. Enabling Secure Connections to JBoss for Single-Node EKM Server

(Optional)
This section applies only to single-node EKM servers.
Communications between the client browser and the application server (JBoss) can either be unencrypted
(HTTP) or encrypted (HTTPS). In order to support encrypted connections, the application server must
possess a signed Secure Sockets Layer (SSL)/TLS certificate (commonly referred to as a cert) and must
be configured to enable encrypted connections over HTTPS.
7.8.3.1. Creating and Installing a Test Certificate

In order to test the capability of connecting to the application server over HTTPS, a self-signed test
SSL/TLS certificate can be installed on the application server and signed by the in-house Certificate
Authority (p. 54).
The steps for generating and installing a SSL/TLS certificate are as follows:
1. Generate a CSR (p. 59) (Certificate Signing Request) for the application server.
2. Sign the CSR (p. 60) with the local CA to produce a signed SSL/TLS certificate.
3. Install the signed certificate (p. 60) on the application server.
7.8.3.1.1. Generating a Certificate Signing Request (CSR)

Follow the instructions below to generate a certificate signing request (CSR) on the EKM cluster node.
User inputs are highlighted in bold.
1. Create the directory: JBOSS_HOME/domain/configuration/keystore
The JBoss server’s private key and certificate will be stored in this directory.
2. In the JBOSS_HOME/domain/configuration/keystore directory, generate a private key for the

application server:
JBOSS_HOME/domain/configuration/keystore>openssl genrsa -out server.key 1024
............++++++
................++++++
e is 65537 (0x10001)
The keystore directory will now contain the private key for the JBoss server, in the file serv
er.key.
3. In the JBOSS_HOME/domain/configuration/keystore directory, generate a CSR for the applic-

ation server. When completed, the keystore directory will contain the CSR for the JBoss server in the
file: server.csr:
JBOSS_HOME/domain/configuration/keystore>openssl req -new -key server.key -out server.csr

What you are about to enter is what is called a Distinguished Name or a DN.
-----
Country Name (2 letter code) [AU]:Your Contry Code
Organization Name (eg, company) [Internet Widgits Pty Ltd]:Your Organization Name
Email Address []:
Please enter the following 'extra' attributes
to be sent with your certificate request
A challenge password []:
An optional company name []:
Note
The Common Name is the host name that is used to connect to the application server.
This is usually the Fully Qualified Domain Name (FQDN) of the server, for example:
ekm.yourdomain.com. A certificate is valid only for the common name it is issued
for; if the name that is used to connect to the ekm server is changed, then a new certi-
ficate for the new common name will need to be issued.
7.8.3.1.2. Signing the CSR

Follow the instructions below to “sign” a certificate signing request (CSR). User inputs are highlighted
in bold.
1. If necessary, copy the CSR file you created in the previous step (p. 57) into the requests directory of the
in-house Certificate Authority.
2. Sign the Certificate Signing Request using the in-house Certificate Authority:
C:\ssl>openssl x509 -req -days 1825 -in requests\server.csr -CA CA\CA.crt
-CAkey CA\CA.key -CAcreateserial -out certs\server.crt
Signature ok
subject=/CN=ekm.yourdomain.com/OU=none/O=Your Organization Name/L=Your
Locality Name/ST=Your State/C=US
Getting CA Private Key
Enter pass phrase for CA\CA.key:
The self-signed SSL/TLS certificate produced by this command is named server.crt and is located
in the certs directory of the in-house CA. This certificate is now ready to install on your application
server.
7.8.3.1.3. Installing the Certificate on the Application Server

Follow the instructions below to install a certificate on the JBoss application server. User inputs are
highlighted in bold.
1. Copy the self-signed certificate to the keystore directory that was created for the application server in
a previous step.
Windows:
copy c:\ssl\certs\server.crt JBOSS_HOME\domain\configuration\keystore
Linux:
cp ssl/certs/server.crt JBOSS_HOME/domain/configuration/keystore
2. Export the certificate to PKCS#12 format:

JBOSS_HOME/domain/configuration/keystore>openssl pkcs12 -export -in server.crt
-inkey server.key -out server.p12 -name default -CAfile c:\ssl\CA\CA.crt
Enter Export Password: <export password>
Verifying - Enter Export Password:
Remember the <export password> you entered – it will be needed later.
3. Create a Java keystore using the Java keytool and import the PKCS#12 certificate into the keystore:
JBOSS_HOME/domain/configuration/keystore>keytool -importkeystore -deststorepass <secret password>
-destkeypass <secret password> -destkeystore mycompany.com.jks -srckeystore server.p12
-srcstoretype PKCS12 -srcstorepass <export password> -alias default
Where:
<secret password> is a secret password for the keystore.
<export password> is the export password provided when the certificate was exported to
PKCS#12 format.
In the example above, the keystore file is created as: mycompany.com.jks. Substitute a filename
appropriate for your deployment when creating the keystore.
4. Edit the JBoss host controller configuration (p. 120):
Add a security-realm child element named SslRealm to the security-realms element.

This will be used to secure the HTTPS connection using the certificate in the keystore. See the ex-
ample below in bold:
<management>
<security-realms>
...
<security-realm name="SslRealm">
<server-identities>
<ssl>
<keystore path="keystore/mycompany.com.jks" relative-to="jboss.server.config.dir"
keystore-password="secret password"/>
</ssl>
</server-identities>
</security-realm>
Provide the secret password for the keystore in the value of the keystore-password attribute
in the keystore element.
5. Edit the JBoss domain Configuration (p. 120):
Add an HTTPS listener to the undertow subsystem. Undertow is the name of the built-in webserver
of JBoss. See the example below in bold:
...
<https-listener name="https" socket-binding="https" security-realm="SslRealm"/>
6. Edit EKM_HOME/conf/ekm.xml and set the value of ekmUrl to the secure URL for EKM. If the value
currently is:
<ekmUrl>http://ekm.yourdomain.com/ekm:8080</ekmUrl>
Change it to:
<ekmUrl>https://ekm.yourdomain.com/ekm:8443</ekmUrl>
Note
If the cluster node uses a JBoss port offset other than the default 0, adjust the port
numbers in the URL accordingly.
7. Start the cluster node.
7.9. Securely Connecting to EKM (Optional)

If you have enabled secure connections on the front-end web server or in JBoss on a single-node EKM
server, connect to EKM on the following URL, using HTTPS instead of HTTP:
EKM Secure URL: https://ekm.yourdomain.com/ekm
where ekm.yourdomain.com is the name of the front-end web server or JBoss server (single-node
EKM server only). The EKM login window should appear in your browser. You are now accessing EKM
securely via an encrypted HTTPS connection. You should see a visual indication in your browser that
you are connected securely to EKM, such as a "lock" icon in the URL entry field and in the lower right-
hand corner of the browser window.
Connecting to EKM from Workbench or Another EKM Server Using HTTPS

If you are using a certificate from a trusted Certificate Authority (CA) to secure your EKM server, you
can securely connect to EKM from Workbench without any additional setup. The same applies when
you are using the Expand Search feature in EKM to expand a search to another EKM server.
If, on the other hand, you are using a self-signed certificate, you must import the certificate into Java's
keystore (p. 62). Otherwise, Java will not trust the certificate that you are using to secure the server,
and will therefore not create a secure connection.
The Java Runtime Environment (JRE) has a file named cacerts that contains a list of trusted CA certi-
ficates that the JRE uses to negotiate secure connections. Self-signed or unknown CA certificates must
be explicitly imported into the cacerts file in order for Workbench or another EKM server to successfully
connect to EKM using HTTPS.
Importing a Self-signed Certificate into Java’s Keystore

If you are using a self-signed certificate to secure an EKM server, follow the steps below to import the
certificate into Java’s keystore.
Securely Connecting to EKM (Optional)
1. Export the self-signed certificate to a file using a browser, or obtain the certificate file from the server.
If using a browser, the steps for exporting a certificate will vary for each type of browser (Chrome,
Firefox, and so on). Consult the documentation for your browser for more information.
If obtaining the certificate file from the server, the method will depend on the web server being
used, and the way in which the certificate was installed on the server.
2. Use the command line to import the certificate into the cacerts file.
The example below shows the command line when importing the certificate for Workbench:
C:\Users\username>keytool -import -alias EKM -keystore
"C:\ANSYS Inc\v170\EKM\programs\jre1.8.0_40\lib\security\cacerts"
-file "C:\Apache\conf\keystore\EKM.crt"
Note that the path will be different depending on the application for which you are importing the
certificate. For example, if you are importing the certificate for an EKM server, the command line
may look like this:
C:\Users\username>keytool -import -alias EKM -keystore
"C:\ekm\v170\programs\jre1.8.0_40\jre\lib\security\cacerts"
-file "C:\Apache\conf\keystore\EKM.crt"
3. When prompted, enter the password of the client keystore. The example below shows the default password
on every JRE cacerts file: changeit.
Enter keystore password: changeit
4. When prompted to trust the certificate, enter yes.

Trust this certificate? [no]: yes
The following confirmation is displayed:

Certificate was added to keystore
Chapter 8: Configuring Login Authentication and Access Settings
Support for EKM authentication and workspace access is provided through login modules. These login
modules are based on the JAAS (Java Authentication and Authorization Service) standard. EKM can be
configured to use any JAAS-compliant login module.
When users log in to EKM they can be authenticated to the operating system, or to an LDAP server.
You must configure the login module prior to specifying any workspace or access settings. For details
see Configuring Login Authentication (p. 65).
After you have configured the login module, it is recommended that you verify or specify values for
the following settings in the ekm.xml file prior to starting the EKM server:
• Default workspace
• Default Root User
• RSM Windows domain
For details see Configuring Login-related Access Settings (p. 73).
8.1. Configuring Login Authentication

Login authentication is provided by an external authentication service. EKM supports two methods of
authentication: LDAP and Operating System (OS) authentication. Integrating EKM with existing IT infra-
structure in this way simplifies management and reduces the number of passwords users need to keep
track of. The table below shows the tested and supported authentication login modules for EKM.
Table 8.1: Supported Login Modules for Authentication
Authentication Authentication Service JAAS-compliant Short Name for

Method Login Module Login Module
LDAP Any LDAP-compliant com.sun.secur- LdapLoginModule
Directory Service ity.auth.mod-
ule.LdapLogin- See Authenticating
Module EKM Logins to an
LDAP
Server (p. 66).
Windows Active Directorya com.sun.secur- LdapLoginModule
ity.auth.mod-
ule.LdapLogin- See Authenticating
Module EKM Logins to
Windows Active
Directory (p. 69).
Operating OS-based authentication waffle.jaas.Win- WindowsLoginModule
System (OS) (Windows) dowsLoginMod-
ule
Configuring Login Authentication and Access Settings
Authentication Authentication Service JAAS-compliant Short Name for

Method Login Module Login Module
Authenticating EKM
Logins to the
Windows Operating
System (p. 71)
OS-based authentication com.ansys.in- LinuxLoginModule
(Linux) gress.core.se-
curity.LinuxLo- See Authenticating
ginModule EKM Logins to the
Linux Operating
System (p. 71).
a
Active Directory features an LDAP interface that can be used for authentication.
By default, WindowsLoginModule is used for authentication in Windows, and LinuxLoginModule

is used for authentication in Linux.
Note
For all authentication login modules, the flag must be set to requisite, and should not
be changed.
8.1.1. Authenticating EKM Logins to an LDAP Server

EKM supports both standard and proxy-based LDAP authentication. To enable and configure LDAP au-
thentication, you must edit the JBoss domain configuration (p. 120). Additional steps may be required
depending on your chosen LDAP authentication method.
Refer to the section below that is pertinent to your setup:
Configuring Standard LDAP Authentication (p. 66)

Configuring Proxy-based LDAP Authentication (p. 68)
8.1.1.1. Configuring Standard LDAP Authentication

To authenticate EKM user logins to an LDAP server, follow the steps below to enable and configure
LdapLoginModule.
1. Stop the EKM server.
2. Edit the JBoss domain configuration (p. 120).
a. Find the security subsystem configuration element:

<subsystem xmlns="urn:jboss:domain:security:1.2">
In the security-domains child element, find the security-domain child element named
other.
In the authentication child element, disable the current login module (either Window-
sLoginModule or LinuxLoginModule) by commenting out the appropriate line.
Windows:
Configuring Login Authentication
<login-module code="waffle.jaas.WindowsLoginModule" flag="requisite" />
Linux:
<login-module code="com.ansys.ingress.core.security.LinuxLoginModule" flag="requisite" />
b. In the authentication child element, add a login-module child element for LdapLoginMod-
ule (shown below in bold).
Note
The login-module element for LdapLoginModule must precede the login-

module element for EkmDefaultMappingAuthenticationModule.
<security-domains>
<security-domain name="other" cache-type="default">
<authentication>
...
...
<login-module code="com.sun.security.auth.module.LdapLoginModule" flag="requisite">
<module-option name="userProvider" value="ldap://ldapserver.yourdomain.com" />
<module-option name="authIdentity" value="uid={USERNAME},ou=users,dc=yourdomain,dc=com" />
<module-option name="useSSL" value="false" />
<module-option name="storePass" value="true" />
<module-option name="tryFirstPass" value="true" />
</login-module>

<login-module code="com.ansys.ingress.core.security.EkmDefaultMappingAuthenticationModule"
flag="requisite" />
3. Edit the configuration of the LdapLoginModule to configure it for your LDAP server. Set the following
module-option values:
userProvider: Set the value to the LDAP URL of the LDAP server.
authIdentity: This specifies the identity to use when authenticating to the LDAP server.
{USERNAME} is a special token that is replaced with the EKM user name that is attempting to sign
in — do not alter it. This string should be constructed such that it maps EKM user names to iden-
tities in your LDAP server. The example here maps EKM user names to LDAP distinguished names
(DN).
Note
Although LDAP may be configured to ignore case, EKM user names are case-sensitive.
Also, EKM will only allow one version of a user name in the same workspace. For more
information see How User Logins Work (p. 72).
For example, based on the above configuration, the uid attribute may be configured
in LDAP as case-insensitive and allow either jsmith or JSMITH to be authenticated
by your LDAP server:
dn: uid=jsmith,ou=users,dc=yourdomain,dc=com
dn: uid=JSMITH,ou=users,dc=yourdomain,dc=com
However, because EKM user names are always case-sensitive, EKM will accept only one
of these versions. The version that EKM accepts is:
• The first user name to be used to sign in to EKM if the user account does not yet exist in
EKM, and automatic account creation is enabled. Or,
• The user name that exactly matches the user name specified in an existing EKM user account.
storePass: This value must be set to true.
tryFirstPass: This value must be set to true.
4. Start the EKM server.
8.1.1.2. Configuring Proxy-based LDAP Authentication

For proxy-based LDAP authentication, follow the steps below to enable and configure LdapLoginMod-
ule.
2. Configure the EKM control scripts and Java Service Wrapper configuration (Windows only) to enable
proxy-based LDAP authentication, by uncommenting specific configuration instructions. These instructions
are preceded with the remark “Uncomment the next line for Proxy-Based LDAP Authentication” for easy
identification.
Windows:
1. Uncomment the following instruction in the ekm_start control script:
EKM_ROOT170/bin/ekm_start.cmd
rem set OPTS=%OPTS% -Dorg.jboss.security.simpleprincipal.equals.override=true
2. Uncomment the following instruction in the Java Service Wrapper configuration on each cluster node:
JBOSS_HOME/domain/configuration/wrapper.conf
#wrapper.java.additional.33=-Dorg.jboss.security.simpleprincipal.equals.override=true
Linux:
Uncomment the following instruction in the ekm_start control script:
EKM_ROOT170/bin/ekm_start.sh
#OPTS="$OPTS -Dorg.jboss.security.simpleprincipal.equals.override=true"

other.
Windows:
Linux:
Note

<security-domains>
...
...
<authentication>
<login-module code="LdapExtended" flag="requisite">
<module-option name="java.naming.provider.url"
value="ldaps://ldapserver.yourdomain.com:636"/>
<module-option name="java.naming.security.authentication" value="simple"/>
<module-option name="bindDN" value="cn=ldap-proxy,ou=systems,ou=yourdomain,o=com"/>
<module-option name="bindCredential" value="ldap-proxy-password"/>
<module-option name="baseCtxDN" value="ou=yourdomain,o=com"/>
<module-option name="baseFilter" value="(uid={0})"/>
<module-option name="rolesCtxDN" value="ou=groups,ou=yourdomain,o=com"/>
<module-option name="roleFilter" value="(member={1})"/>
<module-option name="roleAttributeID" value="cn"/>
<module-option name="roleRecursion" value="0"/>
<module-option name="password-stacking" value="tryFirstPass"/>
</login-module>

flag="requisite" />
In this example, the LDAP proxy user through which all requests will be made is defined in
the bindDN module option.
8.1.2. Authenticating EKM Logins to Windows Active Directory

To authenticate EKM logins to Active Directory, follow the steps below to enable and configure LdapLo-
ginModule.

other.
Windows:
Linux:
Note

<security-domains>
<authentication>
...
...
<login-module code="com.sun.security.auth.module.LdapLoginModule" flag="requisite">
<module-option name="userProvider"
value="ldap://domaincontroller.yourdomain.com/DC=yourdomain,DC=com" />
<module-option name="authIdentity" value="{USERNAME}@yourdomain.com" />
<module-option name="userFilter" value="(& (|(samAccountName={USERNAME})
(userPrincipalName={USERNAME}@yourdomain.com)(cn={USERNAME}))(objectClass=user))" />
<module-option name="useSSL" value="false" />
<module-option name="storePass" value="true" />
<module-option name="tryFirstPass" value="true" />
</login-module>

flag="requisite" />
3. Edit the configuration of the LdapLoginModule to configure it for your Active Directory server. Set the
following module-option values:
userProvider: Set the value to the LDAP URL of a domain controller in the Active Directory
domain.
authIdentity: This specifies the identity to use when authenticating to Active Directory.
{USERNAME} is a special token that is replaced with the EKM user name that is attempting to log
in — do not alter it. This string should be constructed such that it maps EKM user names to user
accounts in Active Directory. The example here maps EKM user names to Active Directory user ac-
counts.
storePass: This value must be set to true.
tryFirstPass: This value must be set to true.
8.1.3. Authenticating EKM Logins to the Windows Operating System

The operating system of the server on which EKM is installed is detected automatically during installation.
If you have installed EKM on a Windows server and want to authenticate users to the Windows operating
system, there is nothing you need to do to enable this behavior. The WindowsLoginModule has
already been enabled in the JBoss domain configuration (p. 120), as shown below:
<security-domains>
<authentication>
...
...
flag="requisite" />
Note
Although user names are case-insensitive when logging in to Windows, they are case-sensitive
when logging in to EKM. Also, EKM will only allow one version of a user name in the same
workspace. See How User Logins Work (p. 72) for more information.
8.1.4. Authenticating EKM Logins to the Linux Operating System

The operating system of the server on which EKM is installed is detected automatically during installation.
If you have installed EKM on a Linux server and want to authenticate users to the Linux operating system,
there is nothing you need to do to enable this behavior. The LinuxLoginModule has already been
enabled in the JBoss domain configuration (p. 120), as shown below:
<security-domains>
<authentication>
...
...
flag="requisite" />
LinuxLoginModule uses PAM (Pluggable Authentication Modules) to authenticate EKM users to the
operating system. LinuxLoginModule uses the sshd PAM service configuration by default. To use
a different PAM service configuration, specify a module option named pam_service_name with a
value of the PAM service name whose configuration you wish to use. For example, to use the configur-
ation for the login service (typically stored at /etc/pam.d/login), use the following LinuxLogin-
Module configuration:
<login-module code="com.ansys.ingress.core.security.LinuxLoginModule" flag="requisite">
<module-option name="pam_service_name" value="login" />
</login-module>
The EKM server account needs access to certain operating system files in order to use LinuxLogin-
Module. This access is configured when creating the EKM server account, as instructed in Create an
EKM Server Account (p. 20).
8.2. How User Logins Work

Each user must specify a user name and password when signing in to EKM. The user name is referred
to as the authentication identity because it may take a different form depending on the configuration.
In the previous section, Configuring Login Authentication (p. 65), you chose a module that will authen-
ticate users via the operating system (WindowsLoginModule or LinuxLoginModule) or
LDAP/Active Directory (LdapLoginModule).
When using an OS-based login module, the authentication identity must be a valid OS account name,
as the module will try to authenticate that identity with the operating system.
If using an LDAP directory for authentication, you have more flexibility. The authentication identity may
be an OS account name or some other unique identifier. It will be based on the RDN of the user entry
that you are using in your Directory Server. This relates to the authIdentity module option specified
in step 3 in Authenticating EKM Logins to an LDAP Server (p. 66).
When a user signs in to an EKM workspace for the first time, and is successfully authenticated, a user
account will be automatically created for that user in the workspace provided that automatic account
creation is enabled in the WorkspaceConfig.xml file (see Configuration Settings in WorkspaceCon-
fig.xml in the Administration Guide). The value entered in the User name field during login will determine
the following for that user:
• EKM user name: The name used to identify the user in EKM (for example, when viewing user accounts on
the Users page, viewing an object’s ownership, or when assigning tasks to users).
• Operating System (OS) account name: The OS account name that will be used to run RSM jobs.
You can also create accounts for users before they log in. See Setting Up Users and Groups in the Ad-
ministration Guide for details.
Important
• User names and passwords are case-sensitive when signing in to EKM, even if the system to which
users are authenticated (LDAP or Windows, for example) is configured to ignore case. For example,
a user may be able to sign in to their Windows machine as jsmith or JSMITH, but if their EKM
user name has been defined as jsmith in a particular workspace, then they cannot sign in to
that workspace using JSMITH.
• EKM will not allow multiple variations of the same user name in a workspace. For example, there
can be a jsmith in Workspace1 and a JSMITH in Workspace2, but there cannot be both a js-
mith and JSMITH in Workspace1. (See Adding a New User in the Administration Guide.)
• If a user has inadvertently created different variations of their user name in different workspaces
(for example, jsmith in Workspace1, and JSMITH in Workspace2), the designated Root User
of a workspace can rename a user by right-clicking the user’s name on the Administration/Users
page and selecting Rename from the context menu.
• Users are signed in to a default workspace at login. If automatic account creation is disabled for
that workspace, and a user account has not been created for a particular user in that workspace,
Configuring Login-related Access Settings
EKM will attempt to sign that user in to another workspace in which automatic account creation
is enabled, or in which a user account has been created for that user. If no workspace meets one
of these criteria, the user will not be able to sign in to EKM.
• The authentication identity entered at login can be mapped to a different user name. See Config-
uring LDAP Mapping (p. 74).
8.3. Configuring Login-related Access Settings

After you have configured the login module, as described in Configuring Login Authentication (p. 65),
you can proceed with specifying the following settings in the EKM_HOME/conf/ekm.xml file:
Table 8.2: Login-related Access Settings
What it means How it is specified

Default The workspace to which all Defined in the defaultDomain
workspace users will connect at login. setting in the ekm.xml file. For
a
more information see Specifying
the Default Workspace
(<defaultDomain>) in the
Administration Guide.
b
Designated Root The only user who will be able The designated Root User is
User to perform restricted specified during installation, but can
configuration on EKM also be specified or changed later.
workspaces.
The EKM user name defined in the
defaultRootUser setting in the
ekm.xml file will be the
designated Root User for all defined
workspaces. See Specifying the
Default Root User
(<defaultRootUser>) in the
Administration Guide for details.
The defaultRootUser setting

can be overridden for a specific
workspace. See the designated-
RootUser setting in Configuration
Settings in WorkspaceConfig.xml in
the Administration Guide.
Important
The value specified for

the Root User must
always be an EKM user
name, and must match
the EKM user name
exactly. The concept of
What it means How it is specified
EKM user names is

described in How User
Logins Work (p. 72).
RSM This is the Windows domain An RSM Windows Domain setting

Windows name that will be prepended is specified during the installation
domain to the user name of all EKM of an EKM server. The value can be
users when batch jobs are modified in the rsmWindowsDo-
(If EKM is submitted to RSM. All user jobs main setting in the ekm.xml file.
configured to will be submitted to RSM as For more information see Specifying
use an RSM rsmWindowsDomain Remote Process Policies
Manager value\OS account name. (<remoteProcess>) in the
running on Administration Guide.
Windows)
a
It is possible for users to log in to other workspaces through the use of cookies, bookmarks, and so on.
b
In order for users to be able to log in to the default workspace, the workspace must meet one of the following criteria:
• It must have automatic account creation enabled (see Configuration Settings in WorkspaceConfig.xml in the Administration Guide for
details)
• If automatic account creation is disabled, user accounts must be manually created (see Adding and Modifying Users in the Administration
Guide)
8.4. Configuring LDAP Mapping

EKM provides two login modules for authentication in addition to those defined in Configuring Login
Authentication (p. 65). They are named EkmDefaultMappingAuthenticationModule and Ekm-
LdapMappingAuthenticationModule. These are referred to as "mapping modules".
The mapping module EkmDefaultMappingAuthenticationModule is enabled by default and

requires no configuration. It serves as a bridge between the external authentication of LDAP or the
Operating System and the EKM server. It is used to determine the access settings defined in Configuring
Login-related Access Settings (p. 73).
The mapping module EkmLdapMappingAuthenticationModule can be enabled in place of Ekm-

DefaultMappingAuthenticationModule by modifying the JBoss domain configuration (p. 120).
EkmLdapMappingAuthenticationModule enables you to map the provided authentication

identity (p. 72) to a new value based on the data in your directory server.
You may choose to use one mapping module or the other depending on your requirements.
Important
You must have either EkmDefaultMappingAuthenticationModule or EkmLdapMap-

pingAuthenticationModule enabled. Both modules cannot be enabled at the same
time, nor can they both be disabled at the same time. The flag of the module that you
choose to use must remain set to requisite.
Configuring LDAP Mapping
When to Use EkmLdapMappingAuthenticationModule

The most common reason for using EkmLdapMappingAuthenticationModule is to authenticate
with LDAP using an e-mail address. Recall that the authentication identity is used for both the EKM user
name and the Operating System (OS) account name. The OS account name is used to run RSM jobs
and must be a valid OS account name. In Example 8.1: LDAP Mapping Using the Default Settings (p. 78),
we have a user who logs in to EKM as joe.adams@company.com, but has an OS account named
jadams. The name used to log in (the e-mail address) needs to be mapped to a different user name
(the OS account name) so that the user can run RSM jobs.
You do not need to use EkmLdapMappingAuthenticationModule if:
• You are using LDAP to authenticate logins but are using a value like a uid that already corresponds to an
OS account name.
• You are using WindowsLoginModule or LinuxLoginModule, because the user name being used to
log in will be a valid OS account that can run RSM jobs.
Enabling EkmLdapMappingAuthenticationModule
If you need to map the authentication identity entered at login to a different user name, you will need
to:

b. In the security-domains child element, find the security-domain child element named
other.
c. In the authentication child element, disable the EkmDefaultMappingAuthentication-

Module login module by commenting it out:

3. In the authentication child element, add a login-module child element for EkmLdapMappingAu-
thenticationModule (shown below in bold):
Note
The login-module element for EkmLdapMappingAuthenticationModule must

follow the commented login-module element for EkmDefaultMappingAuthentic-
ationModule.
<security-domains>
<authentication>
...
...
flag="requisite" />
-->
<login-module code="com.ansys.ingress.core.security.ldap.EkmLdapMappingAuthenticationModule"
flag="requisite">
<module-option name="ldap.authBindDN" value="uid=user,ou=people,dc=example,dc=com" />
<module-option name="ldap.authBindCredential" value="password" />
<module-option name="ldap.baseCtxDN" value="ou=ekm,dc=example,dc=com" />
<module-option name="ldap.userFilter" value="mail={USERNAME}" />
<module-option name="ldap.ekmUsernameAttribute" value="uid" />
<module-option name="ldap.responseTimeout" value="60" />
<module-option name="ldap.searchTimeLimit" value="30" />
<module-option name="ldap.secure" value="false" />
<module-option name="ldap.secureType" value="SSL" />
<module-option name="ldap.serverHost" value="localhost" />
<module-option name="ldap.serverPort" value="389" />
</login-module>
Important
Do not skip the step of disabling EkmDefaultMappingAuthenticationModule. Only

one EKM mapping module can be enabled at a time. Also note that you cannot have both
modules disabled at the same time.
Configuring EkmLdapMappingAuthenticationModule
If you are already using LDAP for authentication (see Configuring Login Authentication (p. 65)), it is
recommended that you configure EkmLdapMappingAuthenticationModule with similar settings
so that this module will find the same data. This is recommended, but not required.
The only requirement is that when searching under the specified ldap.baseCtxDN, a unique entry
matching the ldap.userFilter is found which contains an attribute of the name specified by
ldap.ekmUsernameAttribute.
Important
• If EkmLdapMappingAuthenticationModule is unable to find an entry with an attribute

containing the user name, the EKM login will fail.
• If more than one user entry is found that matches the filter, the EKM login will fail. It is important
to set up the ldap.userFilter carefully so that this is avoided.
Assuming that you have enabled EkmLdapMappingAuthenticationModule, you can configure

it for your LDAP server by setting the following module-option values:
ldap.authBindDN
(optional) Specifies the identity to use when authenticating to the LDAP server. To use anonymous authen-
tication, comment out or delete this option as well as the ldap.authBindCredential option.
Configuring LDAP Mapping
ldap.authBindCredential
(optional) Specifies the password to use when authenticating to the LDAP server. Include this option only
when you have specified a value for ldap.authBindDN.
ldap.baseCtxDN
Specifies the DN (LDAP distinguished name) of the entry in your LDAP server under which to search for a
user. If using LDAP authentication, it is recommended that you use the same value used in that module.
It may not be named ldap.baseCtxDN, but it is the setting that specifies where to search in the directory.
ldap.userFilter
Specifies the LDAP search filter used to find the EKM user entry for the person logging in. The default value
of this setting is mail={USERNAME}. {USERNAME} is a special token that is replaced with the authen-
tication identity (p. 72) that is attempting to log in — do not alter it. The search scope is SUB and the base
DN for the search is defined by ldap.baseCtxDN.
The format of this search filter ranges from simple to complex based on RFC 4515 Lightweight Dir-
ectory Access Protocol (LDAP): String Representation of Search Filters.
The default value mail={USERNAME} will match any entry with a mail attribute equal to the
username token.
Below is an example that will match only inetOrgPerson type entries where either the mail or
uid attribute matches the username token:
(&(|(mail={USERNAME})(uid={USERNAME}))(objectClass=inetOrgPerson))
Note
You must include the attribute that contains the authentication identity in this filter.
If you are using an LDAP/Active Directory login module, then one authentication identity is being
used to both authenticate the user and to look up this mapping information. The authIdentity
and/or userFilter specified for the LDAP/Active Directory login module should be consistent
with this module’s userFilter. As stated above, the only requirement is that when searching
under the specified ldap.baseCtxDN, a unique entry matching the ldap.userFilter is found
which contains an attribute of the name specified by ldap.ekmUsernameAttribute.
Important
Be careful when choosing an attribute to match against {USERNAME}. Each ID must be

unique. If more than one user entry is matched with the search, the EKM login will fail.
ldap.ekmUsernameAttribute
Specifies the attribute containing the name to be used as the EKM user name. When an entry is found
under the ldap.baseCtxDN entry (ou=ekm,dc=example,dc=com in Example 8.1: LDAP Mapping
Using the Default Settings (p. 78)) that is matched by the ldap.userFilter, the value of the
ldap.ekmUsernameAttribute attribute of that entry will be used for the EKM user name in place of
what was entered at login.
ldap.responseTimeout
Specifies the maximum length of time in seconds that an operation should be allowed to block while
waiting for a response from the server. A value of 0 indicates that there should be no timeout.
ldap.searchTimeLimit
Specifies the maximum length of time in seconds that the server should spend processing a search request.
A value of 0 indicates that there should be no limit. Only one search is performed by this module. See
ldap.userFilter above for details.
ldap.secure
Specifies if the connection should be secure. It true, it will be secure and use the encryption method
specified by ldap.secureType. If false, the connection will not be secure.
ldap.secureType
Specifies the encryption method for the secure connection. Supported values are SSL and TLS. Use SSL
for an LDAPS connection. Use TLS when using the extended operation StartTLS. Both SSL and TLS will require
the configuration of the LDAP server with an appropriate certificate.
ldap.serverHost
Specifies the fully qualified hostname where the LDAP server is running (for example, ldapserver.your-
domain.com). If the EKM server is a single-node server and the LDAP server is on the same server host
as the EKM server you may keep the default value of localhost. For any other configuration, including
any multi-node EKM server, do not use localhost.
ldap.serverPort
Specifies the port on which the LDAP server is running.
Standard ports include:
• LDAP: 389/10389
• SSL: 636/10636
• TLS: 389/10389
Example 8.1: LDAP Mapping Using the Default Settings

<module-option name="ldap.baseCtxDN" value="ou=ekm,dc=example,dc=com" />
<module-option name="ldap.userFilter" value="mail={USERNAME}" />
<module-option name="ldap.ekmUsernameAttribute" value="uid" />
A user logs in to EKM as joe.adams@company.com.
EkmLdapMappingAuthenticationModule searches under ou=ekm,dc=example,dc=com for

any entries where mail={USERNAME}, which is mail=joe.adams@company.com. It finds the entry
shown below, which has that value for the mail attribute. It then gets the value of the uid attribute
(as specified by ldap.ekmUsernameAttribute) for that entry. It is jadams. Therefore, the user is
logged in with the user name jadams in place of joe.adams@company.com.
dn: uid=jadams,ou=Users,ou=ekm,dc=example,dc=com
objectClass: top
objectClass: inetOrgPerson
objectClass: person
objectClass: organizationalPerson
cn: Joe Adams
sn: Adams
mail: joe.adams@company.com
uid: jadams
Chapter 9: Installing and Configuring EnginFrame
EKM uses NICE EnginFrame for creating and managing remote visualization sessions, which are used
to run interactive jobs in EKM. EnginFrame supports a number of remote visualization technologies
such as DCV, VNC and HP RGS. It can also work with many job scheduling systems for load balancing
remote visualization jobs. A schematic of the overall system architecture is shown below.
Figure 9.1: Integration of EnginFrame with EKM
EKM and EnginFrame servers can be on the same machine or separate machines. EnginFrame can also
be broken down into EnginFrame Server and EnginFrame Agent, which could be on the same machine
or separate machines. For the purposes of this chapter, it is assumed that both the EnginFrame Server
and EnginFrame Agent will be installed on the same machine.
Here is how the process works:
1. A user logs in to EKM using any of the supported browsers.
2. The user starts a new remote desktop session on an interactive queue configured in EKM.
3. EKM passes this request to EnginFrame, which uses a job scheduler to start a new session on a visualization
server or cluster. The details of the started session are passed back to EKM, and a job object for the session
appears on the user’s Job Monitor page.
Installing and Configuring EnginFrame
4. EKM allows the user to connect to the remote session through the job object on the Job Monitor page.
This opens the Remote Visualization Client on the user’s machine, which enables them to interact with
the remote session.
9.1. EnginFrame System Requirements

This section describes the system requirements for the EnginFrame server, and lists the job schedulers
and remote visualization tools that are supported by EnginFrame.
EnginFrame Server Requirements

EnginFrame can be installed on the following operating systems:
• Red Hat Enterprise Linux 5.x (x86-64)
• Red Hat Enterprise Linux 6.x (x86-64)
• SUSE Linux Enterprise Server 11 (x86-64)
The machine on which EnginFrame is installed must meet the following requirements:
• Minimum 3 GB of RAM
• One or more IP addresses (at least one of them reachable by each of the potential client machines, directly
or via proxies)
• Minimum 200 MB of free disk space (2 GB or more are recommended to ensure that all important data is
saved and logged)
• Oracle’s Java SE 7 (the same Java version should be used for both EnginFrame Server and EnginFrame Agent,
if they are installed on separate machines)
Job Scheduling Systems

EnginFrame supports the following job scheduling systems:
Table 9.1: Job Schedulers Supported by EnginFrame
Name Version Notes

IBM/Platform LSF 6.2 or later The LSF client software must be installed on the
EnginFrame Agent host. The installer will ask you
to specify the LSF profile file.
openlava 2.0 or later The openlava client software must be installed
on the EnginFrame Agent host. The installer will
ask you to specify the openlava profile file.
Adaptive Computing Moab Web 7.2.2 or later The MWS server must be reachable from the
Services (MWS) EnginFrame Server host. The installer will ask you
to specify the IP address of your MWS server.
Altair PBS Professional 7.0 or later The PBS client software must be installed on the
EnginFrame Agent host. The installer will ask you
to specify the directory where the PBS client
software is installed.
EnginFrame System Requirements
Name Version Notes

Torque 3.0 or later The Torque client software must be installed on
the EnginFrame Agent host. The installer will ask
you to specify the directory where the Torque
client software is installed.
NICE Neutro 2013 or later The NEUTRO master(s) must be reachable from
the EnginFrame Server host. The installer will ask
you to specify the IP address of your NEUTRO
master(s).
Sun Grid Engine (SGE) 6.0 or later The Grid Engine client software must be installed
Oracle Grid Engine (OGE) 7.0 or later on the EnginFrame Agent host. The installer will
ask you to specify the Grid Engine shell settings
Univa Grid Engine (UGE) 8.0 or later file.
Open Grid Scheduler 2011 or later
Support for additional job schedulers is available via optional plug-ins. Contact ANSYS support for more
information.
Note
If you are using Moab, Torque or PBS, the enginframe/sessions directory in your Engin-
Frame installation must be accessible to EnginFrame Server, EnginFrame Agent and all visu-
alization nodes.
Remote Visualization Technologies

EnginFrame supports the remote visualization technologies listed in Table 9.2: Remote Visualization
Technologies Supported by EnginFrame (p. 81). A single EnginFrame instance can use multiple remote
visualization technologies simultaneously.
Table 9.2: Remote Visualization Technologies Supported by EnginFrame
Name Version Notes

RealVNC Enterprise Edition 4.5 or later Enables users to share sessions in both full-access
or view-only mode.
TigerVNC 1.0 or later Linux only (server side)
TightVNC 1.3 or later Linux only (server side)
TurboVNC 1.0 or later Linux only (server side)
RealVNC Free Edition 4.1 or later Linux only (server side)
NICE DCV 2011 or later Enables users to share sessions in both full-access
or view-only mode.
VirtualGL 2.1 or later
HP RGS 5.4 or later
Support for additional remote visualization technologies is available via optional plug-ins. Contact ANSYS
support for more information.
9.2. Installing EnginFrame

Before installing EnginFrame, make sure that the machine on which you are installing EnginFrame meets
all necessary requirements. For details see EnginFrame System Requirements (p. 80).
Defining Users Prior to Installing EnginFrame

Before installing EnginFrame, you will need to define two users:
1. An EnginFrame administrator (efadmin hereafter). This user must be an administrator of the selected
distributed resource managers.
2. An unprivileged user for running the EnginFrame portal (efnobody hereafter).
Locating the EnginFrame Installation Files

EKM comes with EnginFrame bundles and installation documents. These can be found in the
EKM_ROOT170/programs/enginframe-2013 directory. This directory contains the following files
and folders:
• An enginframe-ekm-2013.jar file. This is an executable file that contains a customized version of

NICE EnginFrame 2013 for use with EKM.
• An ef-docs folder. This folder contains installation and administration documents for NICE EnginFrame 2013.
These documents describe the installation and configuration of the full EnginFrame server.
Note
The version of EnginFrame that comes with EKM has been customized for use with EKM.
Therefore, many of the installation and configuration steps in the supplied documents are
not required. The instructions provided in this chapter of the EKM Installation Guide are
sufficient for most EnginFrame installations. For advanced deployment and configuration
options not described in this chapter, refer to the documents supplied in the ef-docs
folder.
• A neutro folder. This folder contains installation packages and instructions for NICE Neutro, which can be
used for scheduling remote visualization jobs on Windows machines. Included are the Neutro master server
and Neutro agents for both 32-bit and 64-bit platforms. For an overview of Neutro as well as installation
instructions, refer to the NeutroQuickStartGuide.pdf file that is included in this folder.
Steps for Installing EnginFrame

Follow the steps below to install EnginFrame. Note that EnginFrame can be installed on the same machine
as EKM, or on a separate machine.
1. Log into the machine that will host EnginFrame.
2. Copy the enginframe-ekm-2013.jar from EKM_ROOT170/programs/enginframe-2013 to

the working directory.
3. Assuming that JAVA_HOME is an environment variable pointing to your Java installation, run the following
command as the Root User:
Installing EnginFrame
$JAVA_HOME/bin/java -jar enginframe-ekm-2013.jar
The EnginFrame command-line installation wizard will launch.
4. Follow the prompts in the installation wizard, answering any questions it asks you.
Note
• Installing EnginFrame and EKM on the same machine may result in port conflicts. You may
need to specify a port other than the default during the EnginFrame installation.
Specifically, the following ports may need to be changed:
– Port for Tomcat: Change from 8080 to 8180
– Port at which RMI registry listens for requests: Change from 9999 to 8999
– Port at which EnginFrame agent listens for RMI requests: Change from 9998 to 8998
• During the installation process you will be asked to provide a password for generating an
EKM-EnginFrame certificate. This certificate is used for creating a secure connection between
EKM and EnginFrame. It is important to note this password as you will need it when config-
uring EKM.
• During the installation process you will also be asked to provide host names for the EKM
and EnginFrame servers. These are also needed for generating the EKM-EnginFrame certificate.
If the EKM server is a multi-node server, provide the host names of all cluster nodes separated
by a space.
Starting and Stopping EnginFrame

To start EnginFrame, navigate to the bin folder of the EnginFrame installation and run the following
command as the root user:
./enginframe start
Important
A message will immediately appear confirming that the EnginFrame Server and Agent have
started. However, it may take a few minutes for all services to start running. Therefore, it is
recommended that you wait for 5 minutes before starting EKM.
To stop EnginFrame, issue the following command as the root user:
./enginframe stop
To view the status of EnginFrame, issue the following command:
./enginframe status
9.3. Configuring EKM to Work with EnginFrame

Once EnginFrame has been installed and started, you must execute the steps below to configure EKM
to connect with EnginFrame.
2. The EnginFrame installation creates a hostname.keystore certificate file for each EKM cluster node
in the ekm-certificates folder of the EnginFrame installation. Any of the keystore files created for
an EKM cluster node can be used by all of the EKM cluster nodes. Select one of the hostname.keystore
files, copy it to the EKM_HOME/conf folder, and rename it to ekm.keystore.
3. Configure JBoss to use the ekm.keystore certificate file by modifying the ekm_start.(cmd|sh)
control script. These instructions are already present but commented out in the script. You will need to
uncomment these instructions and change the keystore password if it is different from ekmansys.
If you are running EKM as a service on Windows, these instructions are present in the wrap-
per.conf file as shown below:
#wrapper.java.additional.29=-Djavax.net.ssl.keyStore="%EKM_HOME%\conf\ekm.keystore"
#wrapper.java.additional.30=-Djavax.net.ssl.keyStorePassword=ekmansys
#wrapper.java.additional.31=-Djavax.net.ssl.trustStore="%EKM_HOME%\conf\ekm.keystore"
#wrapper.java.additional.32=-Djavax.net.ssl.trustStorePassword=ekmansys
If you are running EKM in console mode on Windows, these instructions are present in the
ekm_start.cmd control script as shown below:
rem set JAVA_OPTS=%JAVA_OPTS% -Djavax.net.ssl.keyStore="%EKM_HOME%\conf\ekm.keystore"
rem set JAVA_OPTS=%JAVA_OPTS% -Djavax.net.ssl.keyStorePassword=ekmansys
rem set JAVA_OPTS=%JAVA_OPTS% -Djavax.net.ssl.trustStore="%EKM_HOME%\conf\ekm.keystore"
rem set JAVA_OPTS=%JAVA_OPTS% -Djavax.net.ssl.trustStorePassword=ekmansys
If you are running EKM on Linux, these instructions are present in the ekm_start.sh control
script as shown below:
#JAVA_OPTS="$JAVA_OPTS -Djavax.net.ssl.keyStore=$EKM_HOME/conf/ekm.keystore"
#JAVA_OPTS="$JAVA_OPTS -Djavax.net.ssl.keyStorePassword=ekmansys"
#JAVA_OPTS="$JAVA_OPTS -Djavax.net.ssl.trustStore=$EKM_HOME/conf/ekm.keystore"
#JAVA_OPTS="$JAVA_OPTS -Djavax.net.ssl.trustStorePassword=ekmansys"
4. Edit the ekm.xml file and define the <enginframe> settings in the <remoteProcess> section. A
template that is commented out is provided for your convenience. You can uncomment this template
and modify it as needed. The supplied template definition is shown below:
<enginframe>
<serviceDefinitionFile>https://<enginframe-server-name>:8443/enginframe/ekminteractive/ekminteractive.xml
</serviceDefinitionFile>
<adminUser>efadmin</adminUser>
<queue>
<name>Windows Remote Viz Queue</name>
<os>windows</os>
<scheduler>neutro</scheduler>
<schedulerQueue></schedulerQueue>
<remoteType>dcv</remoteType>
</queue>
<queue>
<name>Linux Remote Viz Queue</name>
<os>linux</os>
<scheduler>lsf</scheduler>
<schedulerQueue></schedulerQueue>
<remoteType>dcv</remoteType>
</queue>
</enginframe>
Troubleshooting Tips
Below is a description of the settings that you need to specify:
• serviceDefinitionFile: Replace the <enginframe-server-name> with the fully qualified

host name of the EnginFrame server.
• adminUser: The name of the EnginFrame admin user. The default name is efadmin.
• queue: There can be any number of interactive queues defined. When the EKM server starts, these
queues will be automatically created in the /Administration/Servers/Master folder. You can
specify the following settings for each queue:
– name: The name of the queue as it appears in EKM.
– os: The operating system of the visualization server. The value can be either windows or linux.
– scheduler: The job scheduling system used for creating the session. The value can be lsf,
neutro, pbs, moab, or torque. The value lsf is used for the openlava scheduler.
– schedulerQueue: This is an optional setting that can be used to specify the name of a queue on
the scheduler for creating the session.
– remoteType. The remote visualization technology used. The value can be vnc, dcv, rgs or vir-
tualgl.
5. If you want to add logging for EnginFrame integration for troubleshooting purposes, you will need to
edit the ekm.log4j.properties file in the JBoss configuration directory (see Appendix C: JBoss Domain
Mode and Configuration (p. 120)). You will need to add the following line:
log4j.logger.com.nice=DEBUG, ekmStdout
7. Edit the settings of each newly created interactive queue by navigating to the /Administration/Serv-
ers/Master folder in EKM and then right-clicking the queue and selecting Edit > Job Submission
Settings. For more information see Defining Job Submission Queue Settings in the EKM Administration
Guide.
8. When an interactive queue is created, it will automatically include a predefined application called re-
moteDesktop.app.xml that can be used to start a remote desktop session. You can also create addi-
tional applications in a queue if you want a particular application (for example, ANSYS Workbench) to
launch automatically when the remote session starts. For details on how to do this, see Defining External
Applications Directly in EKM in the EKM Administration Guide.
9.4. Troubleshooting Tips

There are error and warning messages that may occur as you use EnginFrame:
VNC Viewer: "bad Name/Value pair"

Indicates that the VNC Viewer is not compatible with the VNC server.
Starting Remote Desktop: Unable to start interactive job.

May indicate that the "Application Path" of the external application is incorrect.
VNC Viewer: "read/select: Connection reset by peer"

Indicates that the interactive session (or the VNC viewer) is closing because you have closed the interactive
application (such as Workbench) that you initially launched.
VNC Viewer: "connect: Connection refused"

If the session is closed outside of EKM, the session may still be shown on the Job Monitor page for a few
minutes. If you try to reconnect, you may see a message similar to this.
Chapter 10: Starting the EKM Server and Launching the Web Client
Once you have set up an EKM server by running the ANSYS EKM Server product installation (p. 29), you
are now ready to start the EKM server and launch the EKM web client.
Instructions that are specific to Windows versus Linux, or for different server types or configurations
are called out separately throughout the chapter. Follow the instructions for your particular configuration.
Topics in this chapter include:

10.1. Service Mode and Console Mode
10.2. Starting and Stopping the EKM Server in Console Mode
10.3. Launching the EKM Web Client
10.4. Registering and Running EKM as a Service
10.5. Evaluating EKM Log Files
10.1. Service Mode and Console Mode

EKM servers support one or more modes of operation: as a service (“service mode”), and as a console
application (“console mode”).
Console Mode
Console mode describes the mode of running EKM where it is run as a console application. When EKM
is run in console mode, the server is started from a command prompt (Windows) or shell prompt (Linux)
inside a logged-in user session. While the server is running, the console remains open to monitor the
server for messages, such as status, warnings, or errors.
Advantages of running EKM in console mode are:
• No special privileges are required to start and stop EKM
• Easy to start and stop EKM
• Easy to spot startup and runtime errors in server console
Disadvantages of running EKM in console mode are:
• EKM can only be run when a user is logged in
• If the user logs out, the EKM server processes will stop, and must be restarted when the user logs back
in
EKM servers should be run in service mode for production use. Run EKM servers in console mode only
for testing and maintenance because console mode is tied to an active user login.
Starting the EKM Server and Launching the Web Client
Service Mode
Service mode describes the mode of operation where EKM (or an EKM component) is set up to run as
a service under the operating system’s control, independent of any particular user's desktop session or
login shell. This can be done on both Windows and Linux. When run as a service, EKM can be set to
start up when the operating system starts, and it will continue to run whether or not users are logged
into the operating system.
Service mode is the recommended way to run EKM on both Windows and Linux.
10.2. Starting and Stopping the EKM Server in Console Mode

EKM installs a set of control scripts that can be used to start and stop the EKM server in console
mode (p. 87). Control scripts for EKM cluster node(s) and the EKM cluster database server are located
as follows:
• EKM cluster nodes: EKM_NODE_ROOT170/bin
• EKM cluster database server: EKMDB_ROOT/bin
Follow the instructions below to start or stop an EKM server in console mode.
Starting EKM:
1. Start the front-end web server (if applicable).
2. Start the cluster database server:
On the cluster database server, run the mysqld_start.(cmd|sh) control script.
Note
The cluster database server MUST be started before starting any of the cluster
nodes.
3. Start each cluster node:
On each cluster node, run the ekm_start.(cmd|sh) control script.
Stopping EKM:
1. Stop each cluster node:
On each cluster node, run the ekm_stop.(cmd|sh) control script.
2. Stop the cluster database server:
On the cluster database server, run the mysqld_stop.(cmd|sh) control script.
3. (Optional) Stop the front-end web server.
Registering and Running EKM as a Service
10.3. Launching the EKM Web Client

See Launching the EKM Web Client in the EKM User's Guide for details on launching the EKM web client.
10.4. Registering and Running EKM as a Service

Follow the instructions provided below to register and run EKM as a service (or services) on Windows
and Linux systems.
On Windows operating systems, administrative privileges are required to register, unregister, configure
or control (start/stop) Windows services.
Linux operating systems use the System/V init system for registering and running services. Services
are registered and controlled by init scripts located in the /etc/init.d directory. EKM comes with
example init scripts that can be modified and used to register and control EKM as a service. Root
privileges are required to register and control services.
The service or services that are registered to control EKM depend on the server configuration you are
setting up.
Two components that are part of some EKM servers are outside the scope of EKM’s service registration
and control:
• Front-end web server (p. 89)
• Cluster file server (p. 89)

The front-end web server is set up manually. No scripts are provided with EKM for registering or running
the front-end web server as a service. It is recommended that you use the service registration and
control mechanisms provided with the web server to register and run this component as a service.
Cluster File Server

It is not necessary to register the cluster file server component of an EKM server as a service. The cluster
file server uses operating-system-native file sharing functionality that is already enabled and running
on the server host(s) as part of the operating system.
10.4.1. Service Names

Service names on both Windows and Linux must be unique. This is an important consideration when
setting up multiple EKM servers, or multiple instances of an EKM cluster component (such as cluster
nodes) on the same server host. This section outlines the service names used by components on Windows
and Linux, and provides guidance for registering multiple EKM components as services on the same
server host.
10.4.1.1. Windows
Windows services have a display name and a key name. Both the display name and key name for a service
must be unique on the server host on which the service is installed.
EKM components are pre-configured with customized service names that incorporate the cluster name
and/or node name, such that the service names of each cluster component are unique.
Important
In most cases, there is no need to change any of the service names. However, if you need
to change the name of a service, the instructions in this section will explain how to do so.
This section outlines how to create unique service names for different EKM services, based on how the
EKM server is set up. Each entry includes the name of an EKM service, example service display + key
names, and the list of files to edit in order to change the service names.
Service: Cluster Node
• Service Key Name: EKM170_<CLUSTERNAME>_<NODENAME> for example, EKM170_EKMSERVER_NODE1
• Service Display Name: ANSYS EKM Release 17.0 <CLUSTERNAME> <NODENAME> for example, ANSYS EKM
Release 17.0 EKMSERVER NODE1
• Files: JBOSS_HOME/domain/configuration/wrapper.conf
Service: Cluster Database Server
• Service Key Name: EKMDB170_<CLUSTERNAME> for example, EKMDB170_EKMSERVER
• Service Display Name: ANSYS EKM Database Release 17.0 <CLUSTERNAME> for example, ANSYS EKM Release
17.0 Database EKMSERVER
• Files: EKMDB_ROOT/bin/ekm_env.cmd
KEY:
<CLUSTERNAME>: The EKM cluster name.
<NODENAME>: The node name (node ID) of the cluster node.
Renaming a Service:
If you need to rename a service, consult the list above to determine which files need to be edited, and
follow the steps to rename the service.
Cluster Node:
1. If the service is running, stop the service.
2. If the service is registered, un-register the service using the service un-registration script:
EKM_NODE_ROOT170/bin/unregister_ekm_service.cmd
3. Edit JBOSS_HOME/domain/configuration/wrapper.conf and modify the service key and display

names, as well as the service description (shown in bold) according to the guidelines provided above:
wrapper.ntservice.name=EKM170_EKMSERVER_NODE1
wrapper.ntservice.displayname=ANSYS EKM Release 17.0 EKMSERVER NODE1
wrapper.ntservice.description=ANSYS EKM Server Release 17.0 EKMSERVER NODE1

# wrapper.ntservice.dependency.1=EKMDB170
Note
If you are configuring a cluster node that uses the default MySQL database server,
wrapper.conf defines an optional dependency on the EKM database service. Service
dependencies can be used to configure a service to depend on one or more other services
on the same server host. This is useful for a single-node EKM server, where the cluster
database server and cluster node are installed on the same server host. The service key
name of the EKM database service is provided as the value of wrapper.ntservice.de-
pendency.1. This value must match the service key name of the EKM database service
associated with this EKM server. The service dependency must be uncommented to
enable it.
4. Register the service using its service registration script:
EKM_NODE_ROOT170/bin/register_ekm_service.cmd
Cluster Database Server:
Note
All cluster nodes must be stopped before renaming the cluster database service.
1. If the service is running, stop the service.
2. If the service is registered, un-register the service using the service un-registration script:
EKMDB_ROOT/bin/unregister_ekmdb_service.cmd
3. Edit the control script: EKMDB_ROOT/bin/ekm_env.cmd
Find the line that reads:

rem EKM Windows Service Names
Below this line will be service key and display names (shown in bold) for the cluster database
server. Edit these according to the guidelines provided above:
rem EKM Windows Service Names
set EKMDB_SERVICE_KEY_NAME=EKMDB170_EKMSERVER
set EKMDB_SERVICE_DISPLAY_NAME=ANSYS EKM Database Release 17.0 EKMSERVER
4. Register the service using the service registration script:
EKMDB_ROOT/bin/register_ekmdb_service.cmd
10.4.1.2. Linux
Linux service names must be unique. In Linux, service names are defined by init scripts, which are
registered with and executed by the init subsystem. Linux services take their name from the name
of the init script.
An example init script is provided at the following location of each EKM server or cluster component:
• EKM cluster nodes: EKM_NODE_ROOT170/bin/init.d
• EKM cluster database server: EKMDB_ROOT/bin/init.d
This script can be modified to match the configuration of each cluster component. Instructions for ad-
apting the script are provided later in this section.
Note
• The init script provided with EKM follows the LSB model for init scripts, though it is not
verified for compliance with the LSB standard.
• Dependencies between services can be defined by setting properties within init scripts. A
discussion of this is beyond the scope of this guide.
This section outlines how to create unique service names for different EKM services, based on how EKM
is set up. Each entry includes the name of an EKM component, an example service name, and instructions
for creating/adapting an init script for this service.
Service: Cluster Node
• Service Name: ekm170_<CLUSTERNAME>_<NODENAME> for example, ekm170_EKMSERVER_NODE1
• Init Script: ekm170
Service: Cluster Database Server
• Service Name: ekmdb170_<CLUSTERNAME> for example, ekmdb170_EKMSERVER
• Init Script: ekmdb170
KEY:
Renaming a Service:
To rename a service, follow these steps (example: rename ekm170 service to ekm170_EKMSERV-
ER_NODE1):
1. If the service is already registered, stop the service (if necessary), and unregister it:
/etc/init.d/ekm170 stop
/sbin/chkconfig -–del ekm170
2. Rename the service:
a. Rename the init script to the new service name:
mv /etc/init.d/ekm170 /etc/init.d/ekm170_EKMSERVER_NODE1
b. Edit the init script and change the value of the “Provides” tag in the service header to the new service
name:
Old:
# Provides: ANSYS EKM Release 17.0
New:
# Provides: ANSYS EKM Release 17.0 EKMSERVER_NODE1
3. Register the service:
/sbin/chkconfig -–add ekm170_EKMSERVER_NODE1
10.4.2. Running EKM as a Service

Recall from Components of a Cluster Setup (p. 24) that the following components make up an EKM
server cluster:
• One cluster file server
• One cluster database server
• One or more cluster nodes
• One front-end web server
Startup Order:
Cluster components can be set up in different combinations, and on different hosts, so multiple config-
urations are possible. For any EKM cluster, these requirements apply with respect to service startup order:
• The cluster database server must be started before starting any cluster nodes.
• The cluster file server and all required shared directories must be available before starting any cluster
nodes.
If a cluster node is started before the cluster file server or cluster database server are available, the
cluster node must be shut down, and restarted once all missing components are running and available.
Service Registration Scripts:

The following EKM cluster components are registered as services using scripts supplied with EKM:
• Cluster database server
• Cluster nodes
EKM does not include scripts to register the following cluster components as services:
• Front-end web server: See Front-End Web Server (p. 89)
• Cluster file server: See Cluster File Server (p. 89)
The ANSYS EKM Server product installation is used to set up the cluster database server and cluster
nodes. On Windows, service registration scripts are created by the product installation. On Linux, example
init scripts are provided for the cluster database server and cluster nodes.
10.4.2.1. Windows
A cluster database server includes scripts that can be used to register the cluster database server as a
Windows service. These scripts are located in EKMDB_ROOT/bin:
• register_ekmdb_service.cmd: Register cluster database server Windows service.
• unregister_ekmdb_service.cmd: Unregister cluster database server Windows service.
The service registration script for the cluster database server creates the following service:
• ANSYS EKM Database 17.0 <CLUSTERNAME>: This service corresponds to the cluster database server
(MySQL) that contains the EKM database.
Cluster Node:
A cluster node includes scripts that can be used for registration of the cluster node as a Windows service.
These scripts are located in EKM_NODE_ROOT170/bin:
• register_ekm_service.cmd: Register cluster node Windows service.
• unregister_ekm_service.cmd: Unregister cluster node Windows service.
The service registration script for the cluster node creates the following service:
• ANSYS EKM 17.0 <CLUSTERNAME> <NODENAME>: This service corresponds to the cluster node, and
controls the JBoss application server which hosts the EKM server application.
KEY:
10.4.2.2. Linux
The init scripts for the cluster database server and cluster nodes must be manually installed after
setup of these components. Instructions for installing, registering and using these scripts follow.
Important
Recall from the discussion of Service Names that services on a host must have unique names.
Follow the instructions in Service Names (p. 89) to create unique service names for each
cluster component.

To register the cluster database server as a service, use the init script for the cluster database server:
EKMDB_ROOT/bin/init.d/ekmdb170
1. Rename the script, following the naming suggestions in Renaming a Service (p. 92). For example, we
will use ekmdb170_EKMSERVER as the new service name:
mv EKMDB_ROOT/bin/init.d/ekmdb170 EKMDB_ROOT/bin/init.d/ekmdb170_EKM-
SERVER
2. Copy the init script to the /etc/init.d directory:
cp EKMDB_ROOT/bin/init.d/ekmdb170_EKMSERVER /etc/init.d
3. Edit the init script and set the EKMDB_ROOT environment variable to the base directory of the
cluster database server. For example:
EKMDB_ROOT=/home/ekmdb
4. Edit the init script and set the EKM_USER environment variable to the user name of the EKM server
account. For example:
EKM_USER=ekm
5. Register and enable the service:
/sbin/chkconfig -–add ekmdb170_EKMSERVER
6. Verify that the service is registered and enabled:
/sbin/chkconfig -–list ekmdb170_EKMSERVER
Cluster Node:
To register a cluster node as a service, use the init script for the cluster node:
EKM_NODE_ROOT170/bin/init.d/ekm170
1. Rename the script, following the naming suggestions in Renaming a Service (p. 92). For example, we’ll
use ekm170_EKMSERVER_NODE1 as the new service name:
mv EKM_NODE_ROOT170/bin/init.d/ekm170
EKM_NODE_ROOT170/bin/init.d/ekm170_EKMSERVER_NODE1
2. Copy the init script to the /etc/init.d directory:
cp EKM_NODE_ROOT170/bin/init.d/ekm170_EKMSERVER_NODE1 /etc/init.d
3. Edit the init script and set the EKM_BASE environment variable to the base directory of the cluster
node. For example:
EKM_NODE_ROOT=/home/ekm/node1
4. Edit the init script and set the EKM_USER environment variable to the user name of the EKM server
account. For example:
EKM_USER=ekm
5. Register and enable the service:
/sbin/chkconfig -–add ekm170_EKMSERVER_NODE1
6. Verify that the service is registered and enabled:
/sbin/chkconfig -–list ekm170_EKMSERVER_NODE1
The EKM init scripts accept the following command-line arguments:
• start: starts the service
• stop: stops the service
• restart: restarts the service
When a cluster component is registered as a service, the service starts at system startup, and stops at
system shutdown. The init script can also be run directly from the command-line to stop, start, and
restart the service.
10.5. Evaluating EKM Log Files

10.5.1. Log Files
The JBoss application server writes log files to the following log directories:
• JBOSS_HOME/domain/log: Logs for process controller and host controller processes.
• JBOSS_HOME/domain/servers/<servername>/log: Logs for application server processes. This

directory will contain the EKM-related logs.
10.5.1.1. JBoss Log Files

The following log files are created:
• error.log: JBoss application server error log file.
• server.log: JBoss application server runtime log file.
• wrapper.log: (Windows service only) Java Service Wrapper log file.
error.log: Contains only log messages of severity ERROR generated during execution of the JBoss
application server. This log file will contain errors reported by EKM.
server.log: Contains all log messages generated during execution of the JBoss application server.
This log file will contain errors reported by EKM.
Evaluating EKM Log Files
wrapper.log: (Windows service only) Contains log messages generated by Java Service Wrapper,
which is used to run the JBoss application server as a Windows service.
Important
Look in error.log first when looking for errors related to EKM. All log messages in er-
ror.log also appear in server.log, but error.log only contains log messages of
severity ERROR.
Chapter 11: Upgrading an EKM Server from a Previous Version
This chapter outlines the procedure for upgrading an EKM server from EKM 16.0, 16.1 or 16.2 to EKM
17.01. It is intended for use by system administrators and engineers with intermediate or better experience
with Information Technology (IT) systems and configuration.
This chapter discusses:

11.1. Variables and Common Commands
11.2. Prerequisites
11.3. Steps for Upgrading an EKM Server
Before proceeding to Steps for Upgrading an EKM Server (p. 102), familiarize yourself with the Variables
and Common Commands (p. 99) that are used throughout the upgrade process, and carefully review
the Prerequisites that must be fulfilled before performing an upgrade.
The instructions and examples in this chapter refer to an upgrade from version 16.0. If upgrading from
version 16.1 or 16.2, simply substitute the version number where appropriate. Any instructions that are
specific to the version of EKM you are upgrading from (16.0, 16.1 or 16.2) will be called out separately
in the instructions.
11.1. Variables and Common Commands

EKM path variables (p. 99) and common commands (p. 100) that are used when upgrading an EKM
server from a previous version are described here.
11.1.1. EKM Path Variables

We will use these “EKM path variables” as shorthand terms to describe locations of files or directories
and other important information related to the upgrade process. It is not necessary to define any actual
environment variables before upgrading EKM.
EKM 16.0:
• EKM_BASE_160: EKM_BASE directory for EKM 16.0
• EKM_HOME_160: EKM_HOME directory for EKM 16.0
• MYSQL_BASE_160: MYSQL server base directory for EKM 16.0
EKM 17.0:
• EKM_ROOT170: EKM_ROOT170 directory for EKM 17.0
• EKM_NODE_ROOT170: EKM_NODE_ROOT170 directory for EKM 17.0
1
Upgrading directly to EKM 17.0 from EKM versions older than version 16.0 is not supported. You must first upgrade your older EKM
server to EKM 16.0 or later before upgrading to EKM 17.0.
Upgrading an EKM Server from a Previous Version
• EKM_HOME_170: EKM_HOME directory for EKM 17.0
• EKMDB_ROOT_170: EKMDB_ROOT directory for EKM 17.0
• REPOSITORIES_HOME_170: REPOSITORIES_HOME directory for EKM 17.0
11.1.2. Common Commands

Common commands for starting the EKM Database (p. 101), stopping the database (p. 101), starting the
EKM server (p. 101), and stopping the server (p. 101) that are repeated throughout this chapter are doc-
umented here, and referred to using shorthand hereafter.
Start the EKM Server

EKM 17.0
• On the cluster database server, start the EKM database server (p. 101).
• On each cluster node, start the EKM application server (p. 101).
EKM 16.0
Production Non-Cluster:
• On the EKM database server, start the EKM database server (p. 101).
• Start the EKM application server (p. 101).
Production Cluster:
• On the cluster database server, start the EKM database server (p. 101).
• On each cluster node, start the EKM application server (p. 101).
Stop the EKM Server

EKM 17.0
• On each cluster node, stop the EKM application server (p. 101).
• On the cluster database server, stop the EKM database server (p. 101).
EKM 16.0
Production Non-Cluster:
• Stop the EKM application server (p. 101).
• On the EKM database server, stop the EKM database server (p. 101).
Production Cluster:
• On each cluster node, stop the EKM application server (p. 101).
• On the cluster database server, stop the EKM database server (p. 101).
Variables and Common Commands
Start the EKM Database Server

EKM 17.0
• Default MySQL database server: Run EKMDB_ROOT_170/bin/mysqld_start.(cmd|sh)
• Existing database server: On the database server hosting the EKM database, start the EKM database.
EKM 16.0
Production Non-Cluster or Production Cluster:
• Default MySQL database server: Run MYSQL_BASE_160/bin/mysqld_start.(cmd|sh)
• Existing database server: On the database server hosting the EKM database, start the EKM database.
Stop the EKM Database Server

EKM 17.0
• Default MySQL database server: Run EKMDB_ROOT_170/bin/mysqld_stop.(cmd|sh)
• Existing database server: On the database server hosting the EKM database, stop the EKM database.
EKM 16.0
Production Non-Cluster or Production Cluster:
• Default MySQL database server: Run MYSQL_BASE_160/bin/mysqld_stop.(cmd|sh)
• Existing database server: On the database server hosting the EKM database, stop the EKM database.
Start the EKM Application Server

EKM 17.0
On each cluster node, run EKM_NODE_ROOT170/bin/ekm_start.(cmd|sh)
EKM 16.0
Production Non-Cluster: Run EKM_BASE_160/bin/ekm_start.(cmd|sh)
Production Cluster: On each cluster node, run EKM_BASE_160/bin/ekm_start.(cmd|sh)
Stop the EKM Application Server

EKM 17.0
On each cluster node, run EKM_NODE_ROOT170/bin/ekm_stop.(cmd|sh)
EKM 16.0
Production Non-Cluster: Run EKM_BASE_160/bin/ekm_stop.(cmd|sh)
Production Cluster: On each cluster node, run EKM_BASE_160/bin/ekm_stop.(cmd|sh)
11.2. Prerequisites
The Upgrade wizard can be used to upgrade to EKM 17.0 only if specific prerequisites are satisfied. If
any of the following prerequisites is not satisfied, you cannot use the Upgrade wizard, and should
contact your ANSYS EKM support specialist for assistance in upgrading EKM manually.
• The old EKM server version is EKM 16.0 or later.
• The old EKM server type is production, not evaluation.
• The old EKM server has been prepared for an upgrade (see Prepare the EKM 16.0 Server for an Up-
grade (p. 102)).
• One of the cluster nodes of the new EKM server must be on the same server host as the old EKM server (non-
cluster configuration) or one of the cluster nodes of the old EKM server (cluster configuration).
• The EKM database is prepared for an upgrade (see Prepare the EKM Database for an Upgrade – Part 1 (p. 103)
and Prepare the EKM Database for an Upgrade – Part 2 (p. 105)).
• The new EKM 17.0 server fulfills all of its installation prerequisites (see EKM Server Prerequisites (p. 15)).
Steps for Upgrading an EKM Server (p. 102) provides details on how to fulfill these prerequisites.
11.3. Steps for Upgrading an EKM Server

This section describes the steps needed to perform an upgrade, including details on fulfilling all the
prerequisites described in the previous section.
The steps for upgrading an EKM server are:

11.3.1. Prepare the EKM 16.0 Server for an Upgrade
11.3.2. Prepare the EKM Database for an Upgrade – Part 1
11.3.3. Set Up a New EKM 17.0 Server for an Upgrade
11.3.5. Pre-Upgrade Instructions
11.3.6. Launch the Upgrade Wizard
11.3.7. Run the Upgrade Wizard
11.3.8. Review the Post-Upgrade Instructions
11.3.9. Post-Upgrade Instructions
11.3.1. Prepare the EKM 16.0 Server for an Upgrade

This section describes the steps needed to prepare an EKM 16.0 server for an upgrade. These steps are:
1. Before upgrading, ensure that no workspace is in configuration mode.
2. Verify the existing EKM 16.0 installation. (p. 102)
3. Back up EKM 16.0. (p. 103)
11.3.1.1. Verify the Existing EKM 16.0 Installation

Begin your upgrade preparations by verifying the existing EKM 16.0 installation. Verify the location of
the EKM base directory, referred to as EKM_BASE_160. For example:
Steps for Upgrading an EKM Server
Windows: c:\ekm\v160
Linux: /home/ekm/v160
EKM_HOME_160 refers to the EKM_HOME directory of the existing EKM 16.0 installation:
EKM_BASE_160/ekm-server
Verify the server type of your existing EKM 16.0 installation. It will be either Evaluation or Production.
For a Production server, determine if your configuration is non-cluster, or cluster. For a Production
server in non-cluster configuration, determine if the server uses the default MySQL database server or
an existing database server.
Only production servers may be upgraded to EKM 17.0.
11.3.1.2. Back Up EKM 16.0

Before upgrading to EKM 17.0, it is necessary to perform a full backup of the EKM 16.0 server. Refer to
the Backing Up and Restoring EKM chapter in the EKM 16.0 Administration Guide for more information.
If the upgrade procedure fails, you may need to recover your EKM 16.0 server from backup.
Important
Failure to perform a full backup of EKM 16.0 according to the instructions in the EKM
16.0 Administration Guide could result in unrecoverable loss of data.

EKM provides flexible deployment options for the EKM database and EKM database server. ANSYS EKM
Server product installation provides the option to install a default MySQL database server to host the
EKM database, or to use an existing MySQL or Oracle database server to host the EKM database.
Depending on the configuration of the EKM 16.0 server being upgraded, and the desired configuration
of the new EKM 17.0 server, different steps may be required to prepare the EKM database for an upgrade.
Decisions you make in this step will affect options that must be specified during installation of EKM
17.0 as performed by the ANSYS EKM Server product installation, and may require manual steps to be
performed outside of the product installation.
Special Instructions for EKM Servers that use MySQL Database Server:
EKM 17.0 supports MySQL server version 5.5.41 or higher.
EKM 16.1 and 16.2 servers that use the default MySQL server installed by the ANSYS EKM Server product
installation will have MySQL server version 5.5.41 already. EKM 16.0 servers (version 16.0 only) that use
the default MySQL server installed by the product installation use an older version of MySQL server. On
these servers, the EKM database must be transferred to a new MySQL server with version 5.5.41 or
higher.
An EKM 16.0 server (including EKM 16.0, 16.1 or 16.2) that uses an existing MySQL database server that
is not installed by the ANSYS EKM Server product installation must also use MySQL database server
version 5.5.41 or higher.
ANSYS EKM Server product installation can install a default MySQL database server for EKM 17.0, which
is suitable for transferring an EKM 16.0 database that is hosted on an older version of MySQL server.
Alternatively, a new MySQL database server meeting the minimum version requirement can be installed
manually and used as an existing database server.
In any case where the EKM database must be transferred to a new EKM database server to meet min-
imum version requirements, the transfer of the EKM database from the old EKM database server to the
new EKM database server must be performed prior to executing the Upgrade wizard, and the EKM 17.0
server must be configured to use the new EKM database server that contains the transferred EKM
database.
Preparing the EKM Database:

Choose from the following options to prepare the EKM database for upgrade, based on the configuration
of your EKM database server. The choices you make here will determine certain options you must specify
in the ANSYS EKM Server product installation for EKM 17.0:
• Option: Use the existing EKM 16.0 database:
The EKM 17.0 server is configured to use the same EKM database server and EKM database that are
currently being used by EKM 16.0.
When running the product installation for EKM 17.0: On the Database Server Settings screen, enter
values (host name, port number, database name2, and so on) that match the EKM database server
and EKM database being used by the existing EKM 16.0 server (see Installing a New EKM Server (p. 29)).
Use this option when all of these conditions apply:
– The EKM 16.0 database is hosted on a database server that meets the minimum database server version
requirements for EKM 17.0.
– You do not want to, or do not need to transfer the EKM database to a new EKM database server.
• Option: Use a new EKM database containing the existing EKM 16.0 database data:
The EKM 17.0 server is configured to use a new EKM database that contains the data from the EKM
16.0 database, which has been exported from the old EKM database server and imported into a new
EKM database server. Note that this database transfer may take place before or after running the
product installation, but must be completed prior to executing the Upgrade wizard.
When running the product installation for EKM 17.0: On the Database Server Settings screen, enter
values (host name, port number, database name2, and so on) that match the new database containing
the EKM 16.0 database data (see Installing a New EKM Server (p. 29)). The new database can either
be hosted on the default MySQL database server installed by the product installation, or on a com-
patible database server that is installed separately from EKM.
Use this option when any of the following conditions apply:
– The EKM 16.0 database is hosted on a database server that does not meet the minimum database server
version requirements for EKM 17.0.
2
The ANSYS EKM Server product installation supplies a default value of ekm for the database name. You should change this to be
the name of your EKM 17.0 database.
– You want to—or need to—transfer the EKM database to a new EKM database server.
11.3.3. Set Up a New EKM 17.0 Server for an Upgrade
Important
The new EKM 17.0 Server must be installed on the same server host as the old EKM server.
This requirement is met if one of the cluster nodes of the new server is on the same server
host as the old EKM server (non-cluster configuration) or one of the cluster nodes of the old
EKM server (cluster configuration).
Before you can upgrade to EKM 17.0 from a previous version of EKM, you must first set up a new EKM
17.0 server for an upgrade. To set up a new EKM 17.0 server for an upgrade, follow these steps:
1. Prepare to set up an EKM server by fulfilling all installation prerequisites (see EKM Server Prerequis-
ites (p. 15)). Some key prerequisites are:
• Verify that the ANSYS Multiphysics Products Version 17.0 (see Required Software Applications (p. 17))
is correctly installed, licensed, and tested.
• Verify that ANSYS Licensing is correctly installed, and that licenses for EKM and ANSYS Multiphysics
are installed and available for use (see ANSYS Licensing (p. 18)).
2. Follow the steps in Setting Up an EKM Server (p. 29), making sure to follow the Special Instructions
for Upgrade (p. 35).
3. Follow the steps in Post-Setup (p. 37), making sure to follow the Special Instructions for Upgrade. (p. 41)

Prior to executing the EKM Upgrade wizard, as instructed in Prepare the EKM Database for an Upgrade
– Part 1 (p. 103), the EKM database from the EKM 16.0 server must be available at the location specified
during ANSYS EKM Server product installation for EKM 17.0.
If the EKM database of the EKM 16.0 server needs to be transferred from another database server to
the EKM database server specified during product installation for EKM 17.0, this transfer must be com-
pleted now.
For MySQL database servers, instructions for backing up and restoring a MySQL database in Backing
Up and Restoring EKM provide the instructions necessary to transfer the EKM database from one database
server to another by backing it up on the old server and restoring it on the new server.
11.3.5. Pre-Upgrade Instructions

The EKM Upgrade wizard will be run on one and only one of the cluster nodes of the new EKM 17.0
server. As previously mentioned in the Prerequisites (p. 102), one of the cluster nodes of the new EKM
server must be on the same server host as the old EKM Production server (non-cluster configuration)
or one of the cluster nodes of the old EKM Production server (cluster configuration). The EKM Upgrade
wizard will be run on this one server host, and will upgrade the EKM database and EKM repositories to
EKM 17.0. General Post-Upgrade Instructions (p. 110) and cluster-specific Post-Upgrade Instructions (p. 110)
are then followed to complete the upgrade to EKM 17.0.
Before launching the EKM Upgrade wizard, follow these pre-upgrade instructions:
1. Edit the configuration file EKM_HOME/conf/ekm.xml. Find the modules element and enable the
ekmServer module by setting the value of the enabled attribute to true:
<modules>
<module name="ekmServer" enabled="true" />
</modules>
11.3.6. Launch the Upgrade Wizard
Important
Before proceeding with any of the following steps, it is a requirement that you back up the
EKM 16.0 server, including the database (see Back Up EKM 16.0 (p. 103)). The Upgrade wizard
will upgrade the data in the EKM database to be compatible with EKM 17.0. It will no longer
work with EKM 16.0 once it has been upgraded to work with EKM 17.0.
If there are problems with the EKM upgrade, it may be necessary to restore the EKM 16.0
database before attempting the upgrade again.
EKM 17.0 provides a utility called the EKM Upgrade wizard (“Upgrade wizard”) that helps automate the
upgrade of an old EKM 16.0 server to a new EKM 17.0 server, and converts the EKM server data to the
new EKM 17.0 format.
To launch the Upgrade wizard from the command line on Windows or Linux systems, use the Upgrade
wizard launch script:
EKM_ROOT170/utils/bin/UpgradeEKMServer.(cmd|sh)
Important
The Upgrade wizard should be launched using the EKM server account. This will ensure that
the Upgrade wizard can access all necessary files and EKM data.
Once the Upgrade wizard is launched, follow the steps to run the Upgrade wizard (p. 106) and perform
an upgrade.
11.3.7. Run the Upgrade Wizard

Once you have prepared for an upgrade and set up a new EKM 17.0 server, you are now ready to perform
the upgrade using the Upgrade wizard.
Important
You must fulfill the required prerequisites before running the Upgrade wizard.
Fulfilling the Prerequisites
Important
The Upgrade wizard can be used to upgrade to EKM 17.0 only if specific prerequisites are
satisfied (see Prerequisites (p. 102)).
Before Launching the Upgrade Wizard:
1. Stop the old EKM server.
2. Stop the new EKM server.
3. Start the database server that will be used by the EKM 17.0 database server. This database server must
contain the EKM database from the EKM 16.0 server, which will be upgraded by the Upgrade wizard for
use with EKM 17.0 (see Prepare the EKM Database for an Upgrade – Part 1 (p. 103) and Prepare the EKM
Database for an Upgrade – Part 2 (p. 105)). During the upgrade, you will be asked by the Upgrade wizard
to confirm that this database server is running before proceeding further.
You may now launch the Upgrade wizard using the EKM server account.
4. In the Prerequisites step, click on the links to the Installation Guide to review the prerequisites that are
required for upgrade. Select Prerequisites fulfilled only if all of the requirements are met. Click Next >
to continue.
Figure 11.1: Upgrade Wizard: Prerequisites Step
5. In the Setup Directories step, specify the base directory (EKM_BASE) for the old EKM server (for example,
C:\ekm\v160). This is the setup directory of the old server (non-cluster configuration) or one of the
cluster nodes of the old server (cluster configuration).
Then, specify the base directory (EKM_NODE_ROOT) for a cluster node of the new EKM server (for
example, C:\ekm\node1). Note that in EKM 17.0, every EKM server installation is a cluster config-
uration, even if the cluster has only one node. When upgrading to a multi-node EKM server, specify
the base directory of one of the cluster nodes. The Upgrade wizard is only run on one and only one
cluster node, regardless of how many nodes there are.
Click Next > to continue.
Figure 11.2: Upgrade Wizard: Setup Directories Step
6. In the EKM Database step, confirm that the EKM 16.0 database is ready to be upgraded to work with
EKM 17.0. Select I have fulfilled the requirements only if all of the requirements are met.
Figure 11.3: Upgrade Wizard: Prepare the EKM Database Step
Summary of requirements listed in this dialog:
• Requirement 1
If you have completed the database preparation outlined in (Prepare the EKM Database for an
Upgrade – Part 1 (p. 103) and Prepare the EKM Database for an Upgrade – Part 2 (p. 105)), this
requirement has been met.
• Requirement 2
If not already running, start the database server now for the EKM database shown in the dialog
box.
Click Next > to continue.
7. In the Upgrade step, EKM will upgrade the EKM server data to the EKM 17.0 format. The Upgrading
EKM Server... message will persist during the process. This may take a while. Click Finish when the
upgrade is completed.
Figure 11.4: Upgrade Wizard: Upgrade Step
Note
This is a sample dialog for an upgrade of an EKM server. The output will vary depending
on your specific EKM server configuration.
11.3.8. Review the Post-Upgrade Instructions

The upgrade from EKM 16.0 to EKM 17.0 is now complete.
Before starting EKM, copy any audit log files from the EKM 16.0 log directory (EKM_HOME_160/ekm-
server/logs) to the EKM 17.0 log directory (EKM_HOME_170/ekm-server/logs).
Before using the upgraded EKM server, all users who access the EKM server must clear their browser
caches. This will prevent display problems in the EKM web client that can be caused by cached inform-
ation from the old version of EKM.
11.3.9. Post-Upgrade Instructions

This section documents post-upgrade steps that must be performed before the new EKM server can
be used.
1. Synchronize the Repository Folders on All Cluster Nodes (p. 111)
2. Synchronize the Revision ID for All Cluster Nodes in the Cluster Database (p. 112)
11.3.9.1. Synchronize the Repository Folders on All Cluster Nodes

When upgrading to EKM 17.0, the Upgrade wizard is run on one cluster node of the new server. Along
with updating the EKM database and EKM data directory to EKM 17.0, the Upgrade wizard updates the
content of the REPOSITORIES_HOME_170 folder of this cluster node. This updated REPOSITOR-
IES_HOME_170 folder needs to be manually synchronized to the other cluster nodes of the new
server after the Upgrade wizard completes.
In the instructions that follow, we present an example scenario of a three-node cluster whose nodes
are named node1, node2, and node3. The Upgrade wizard is run on node1.
1. Save a backup copy of the repository.xml.template on the other cluster nodes, or make a note
of the cluster ID of each cluster node. The cluster ID is set in REPOSITORIES_HOME_170/reposit-
ory.xml.template in the id attribute of the Cluster element, and is set to the value entered for
the EKM cluster node ID during the product installation.
2. Copy the entire REPOSITORIES_HOME_170 directory from node1 of the cluster to each of the other
cluster nodes.
3. Visit each of the other cluster nodes and modify the contents of the REPOSITORIES_HOME_170/re-
pository.xml.template and the repository.xml file within each subdirectory of REPOSITOR-
IES_HOME_170. In each repository.xml file, set the cluster ID back to its original, correct value for
that cluster node.
The following are example paths for REPOSITORIES_HOME_170 in a cluster of three nodes:
c:\ekm\node1\repositories
Example 11.1: Synchronize the repository folders of node2 and node3 with the repository folder
of node1
1. Make note of the cluster IDs of node2 and node3.
a. In REPOSITORIES_HOME_170/repository.xml.template on node2, the cluster ID is node2:

<Cluster id="node2" syncDelay="2000">
b. In REPOSITORIES_HOME_170/repository.xml.template on node3, the cluster ID is node3:

<Cluster id="node3" syncDelay="2000">
2. On node2 and node3, delete the REPOSITORIES_HOME_170 folder.
3. On node2 and node3, copy the c:\ekm\node1\repositories folder to c:\ekm\node2\repos-

itories on node2 and to c:\ekm\node3\repositories on node3 to replace the deleted REPOS-
ITORIES_HOME_170 folder.
4. On node2 and node3, edit REPOSITORIES_HOME_170/repository.xml.template to set the

cluster ID back to the original, correct value for that cluster node.
5. On node2 and node3, for each subdirectory in REPOSITORIES_HOME_170, edit repository.xml

to set the cluster ID back to the original, correct value for that cluster node.
11.3.9.2. Synchronize the Revision ID for All Cluster Nodes in the Cluster Database
Connect to the EKM cluster database and for each repository check the REVISION_ID value for all of
the cluster nodes:
• Each repository is represented in the database by a set of database tables with a common table name prefix
"rN_" where N is a number; for example: r0_ and r1_.
• For each repository with table name prefix rN_, the value of REVISION_ID for all cluster nodes in the
table rN_jl_local_revisions should be the same for all cluster nodes and should be the same as the
value of REVISION_ID in the table rN_jl_global_revision.
An example is shown below, with additional instructions shown in bold:

mysql> use ekm;
Database changed
mysql> show tables like '%revision%';

+----------------------------+
| Tables_in_ekm (%revision%) |
+----------------------------+
| r0_jl_global_revision |
| r0_jl_local_revisions |
| r1_jl_global_revision |
| r1_jl_local_revisions |
+----------------------------+
4 rows in set (0.00 sec)
There are two repositories, with table name prefixes: r0_ and r1_.
mysql> select * from r0_jl_global_revisions;

+-------------+
| REVISION_ID |
+-------------+
| 3255318 |
+-------------+
1 row in set (0.00 sec)
mysql> select * from r0_jl_local_revisions;

+------------+-------------+
| JOURNAL_ID | REVISION_ID |
+------------+-------------+
| node1 | 3255318 |
| node2 | 1347377 |
| node3 | 1473274 |
+------------+-------------+
If there are incorrect values for any of the nodes,

correct the values as shown below. Note that there may
not be values stored for all nodes, so the steps to delete
may not be needed.
delete from r0_jl_local_revisions WHERE JOURNAL_ID='node2';

delete from r0_jl_local_revisions WHERE JOURNAL_ID='node3';
insert into r0_jl_local_revisions (JOURNAL_ID, REVISION_ID) values ('node2', '3255318');

insert into r0_jl_local_revisions (JOURNAL_ID, REVISION_ID) values ('node3', '3255318');
Verify that all values are now the same.
mysql> select * from r0_jl_global_revision;

+-------------+
| REVISION_ID |
+-------------+
| 3255318 |
+-------------+
1 row in set (0.00 sec)
mysql> select * from r0_jl_local_revisions;

+------------+-------------+
| JOURNAL_ID | REVISION_ID |
+------------+-------------+
| node1 | 3255318 |
| node2 | 3255318 |
| node3 | 3255318 |
+------------+-------------+
mysql>
Repeat this procedure for each repository.
Chapter 12: Gathering Support Diagnostics
This chapter outlines the procedure for running the ANSYS 17.0 EKM Server Diagnostics tool (or “EKM
Server Diagnostics tool”) to collect information about an installed EKM 17.0 server to help diagnose
problems. It is intended for use by system administrators and engineers with intermediate or better
experience with Information Technology (IT) systems and configuration.
When you run the tool, a compressed (.zip) support archive file containing logs, configuration files,
and other diagnostic information is written that can be analyzed by your EKM support specialist. The
EKM Server Diagnostics tool supports only EKM 17.0 servers that have been set up using the steps
outlined in Steps for Setting Up an EKM Server (p. 8).
12.1. Launching the EKM Server Diagnostics Tool

You can launch the EKM Server Diagnostics tool from the launch script:
EKM_ROOT170/utils/bin/DiagnoseEKMServer.(cmd|sh)
Once the EKM Server Diagnostics tool opens, follow the steps below to gather diagnostics.
12.2. Using the EKM Server Diagnostics Tool

When you answer the prompts in the EKM Server Diagnostics tool and click Run, a compressed (.zip)
support archive file is created that you can send to your EKM support specialist for analysis. The support
archive file will be written to the root directory of the specified cluster node as follows:
EKM_NODE_ROOT/ekmSupportArchive.zip
1. Enter the EKM node root directory (for example, C:\ekm\node1) or click Browse to select the root
directory of the EKM cluster node. The directory that you select will also be the location where the support
archive file will be written.
Click Run to execute the diagnostics tool. This may take a while to complete. The path to the EKM
support archive file: EKM_NODE_ROOT/ekmSupportArchive.zip is filled in once the utility
starts running.
2. While the diagnostics tool is running, you will not be able to exit. Once completed, click Finish to complete
the process and close the dialog box. The support archive file will be created at the location displayed in
the EKM Server Diagnostics tool dialog box. You can send the support archive file to your EKM support
specialist for analysis.
Chapter 13: Uninstalling an EKM Server
This chapter describes how to uninstall an EKM 17.0 server.
Important
Uninstalling an EKM server will cause the loss of all data stored in the EKM server. You
should only uninstall an EKM server if you are willing to permanently delete all data
stored in the EKM server.
In this chapter:
13.1. Uninstalling an EKM Server on Windows
13.2. Uninstalling an EKM Server on Linux
13.3. Uninstalling the Front End Web Server
13.1. Uninstalling an EKM Server on Windows
Important
Uninstalling an EKM server will cause the loss of all data stored in the EKM server.
1. Stop the EKM server:
a. Stop all cluster nodes.
b. Stop the cluster database server.
2. Unregister all EKM cluster component services:
a. Unregister each cluster node service by running the service unregistration script:
EKM_NODE_ROOT170\bin\unregister_ekm_service.cmd
b. Unregister the cluster database service by running the service unregistration script:
EKMDB_ROOT\bin\unregister_ekmdb_service.cmd
3. Remove the shared EKM data directory; the shared EKM data directory is located on a network file share
on the cluster file server.
4. Remove the shared EKM job data directory; the shared EKM job data directory is located on a network file
share on the cluster file server.
5. Remove the REPOSITORIES_HOME directory of each cluster node.
Uninstalling an EKM Server
6. Remove the EKM_NODE_ROOT directory of each cluster node.
7. Remove the EKMDB_ROOT directory of the cluster database server.
13.2. Uninstalling an EKM Server on Linux
Important
Uninstalling an EKM server will cause the loss of all data stored in the EKM server.
1. Stop the EKM server:
a. Stop all cluster nodes.
b. Stop the cluster database server.
2. Unregister all EKM cluster component services:
a. Unregister each cluster node service (example service name: ekm170_node_EKMSERVER_NODE1):
chkconfig -–del ekm170_node_EKMSERVER_NODE1
b. Unregister the cluster database service (example service name: ekmdb170_EKMSERVER):
chkconfig -–del ekmdb170_EKMSERVER
3. Remove the shared EKM data directory; the shared EKM data directory is located on a network file share
on the cluster file server.
4. Remove the shared EKM job data directory; the shared EKM job data directory is located on a network file
share on the cluster file server.
5. Remove the REPOSITORIES_HOME directory of each cluster node.
6. Remove the EKM_NODE_ROOT directory of each cluster node.
7. Remove the EKMDB_ROOT directory of the cluster database server.
13.3. Uninstalling the Front End Web Server

An EKM cluster integrates with a front-end web server.
If the front-end web server is used exclusively for the EKM server being uninstalled, it may be uninstalled
along with the EKM server. If the front-end web server serves other functions in addition to EKM, the
EKM-specific configurations may be removed. In the later case, complete the uninstall of the EKM
server, then review the Installing a Front-End Web Server (p. 43) chapter to determine which EKM-related
configurations may be removed from the web server.
Chapter 14: Appendices
These appendices to the EKM Installation Guide contain supplemental information for configuring your
EKM server. Follow the instructions for the setup that your particular system requires. Sections that are
specific to Windows or Linux are noted as such.
The appendixes are as follows:

14.1. Appendix A: Setting Environment Variables for EKM
14.2. Appendix B: Network Ports
14.3. Appendix C: JBoss Domain Mode and Configuration
14.4. Appendix D: Email Configuration
14.5. Appendix E: Resolving Network Port Conflicts
14.6. Appendix F: Changing the JBoss HTTP Port
14.7. Appendix G: Setting the HTTP Session Timeout
14.8. Appendix H: Changing the MySQL Database Server Port
14.9. Appendix I: Configuring Windows Services (Windows Only)
14.10. Appendix J: Updating EKM Server Objects
14.11. Appendix K: Granting Database Privileges
14.12. Appendix L: Clearing the Repository
14.13. Appendix M: Disabling HTTP Compression
14.14. Appendix N: Changing the JVM Heap Size
14.15. Appendix O: Configuring EKM to Use Amazon S3 Data Storage
14.16. Appendix P: Creating a Silent Installation File
14.17. Appendix Q: EKM Cluster Network Configuration
14.18. Appendix R: Configuring the MySQL Connector/J JDBC Driver
14.19. Appendix S: Changing the EKM Cluster Name
14.20. Appendix T: Changing an EKM Cluster Node IP Address
14.21. Appendix U: Troubleshooting
14.1. Appendix A: Setting Environment Variables for EKM

EKM uses environment variables to specify the location of various paths and other information. These
environment variables are set differently depending on how you are running EKM. The default locations
of the environment variable settings for different run modes are given below.
Windows:
• Service Mode: See Appendix I: Configuring Windows Services (Windows Only) (p. 133)
• Console Mode: ekm_env.cmd control script
Linux:
• Service Mode: ekm_env.sh control script
• Console Mode: ekm_env.sh control script
Appendices
The ANSYS EKM Server product installation sets the values of these environment variables in the control
scripts and in the wrapper.conf configuration file (where applicable, Windows only) during installation.
14.2. Appendix B: Network Ports

Client to EKM Server Communication:
The web client communicates with EKM servers over certain network ports, which can differ depending
on how EKM is set up and configured. Typical network ports used by the web client to communicate
with EKM servers are given in the table below. If you are accessing EKM through a firewall, these ports
must be allowed between the web client and the EKM server.
Table 14.1: EKM Server Network Ports for Web Client Communication
Port/Protocol Used By
80/TCP HTTP port (front-end web server)
443/TCP HTTPS port (front-end web server)
a
8080/TCP HTTP port (JBoss application server)
a
8443/TCP HTTPS port (JBoss application server)
a
This port number is subject to change according to the JBoss port offset used. See Appendix E: Resolving Network Port Conflicts (p. 129).
Front-End Web Server to EKM Server Communications
EKM servers can be configured to use a front-end web server. Communication between a front-end
web server and EKM server happens using the AJP, HTTP or HTTPS protocols, depending on the config-
uration of the front-end web server and EKM server.
In a scenario where the front-end web server is on a different network than the EKM server, and those
networks are separated by a firewall, the firewall must allow the traffic to pass between the front-end
web server and the EKM server. This scenario is typical when setting up EKM in an internet-facing de-
ployment, where the front-end web server is on a DMZ network, and the EKM server is on an internal
network. The traffic that needs to be allowed between the front-end web server and the EKM server is
listed in the table below:
Table 14.2: EKM Server Network Ports for Front-End Web Server Communication
Port/Protocol Used By
8019/TCP*a mod_cluster (AJP) / JBoss (unencrypted)
or
mod_cluster (HTTP) / JBoss (unencrypted)
8080/TCP*a
or
mod_cluster (HTTPS) / JBoss (encrypted)
8443/TCP*a
a
This port number is subject to change according to the JBoss port offset used. See Appendix E: Resolving Network Port Conflicts (p. 129).
14.3. Appendix C: JBoss Domain Mode and Configuration

EKM servers use the JBoss application server to execute the EKM server application. EKM servers can
use multiple instances of JBoss application server, one for each EKM cluster node.
Appendix C: JBoss Domain Mode and Configuration
JBoss operates in one of two operating modes: standalone or domain. EKM only uses domain mode. In
domain mode, each JBoss instance runs as a collection of specialized processes, and communicates
with other JBoss instances in a “domain”. Domain mode provides centralized management and config-
uration for multiple JBoss instances.
14.3.1. Domain Mode

In a JBoss domain, multiple instances of JBoss work together and are managed centrally by one JBoss
instance which is called the “domain controller”. Other JBoss instances which are members of the domain
are known as "slaves".
In an EKM server, the EKM cluster primary node is initially configured as the JBoss domain controller.
Non-primary nodes are configured as slaves. The domain controller provides centralized configuration
and management for all JBoss instances in the domain.
When a JBoss instance is operated in domain mode, it executes the following processes:
• JBoss Process Controller (“Process Controller”)
• JBoss Host Controller (“Host Controller”)
• JBoss Application Server (“Application Server”)
The Process Controller is a process that manages and starts/restarts other processes. This process and
its configuration are simple; we do not need to be concerned with it.
The Host Controller process is more interesting; this process controls the domain membership of the
JBoss instance, and launches a JBoss Application Server, which executes the EKM server application. In
a JBoss domain, one host controller serves as the domain controller, and the other host controllers are
slaves. The domain controller maintains the master copy of the JBoss Application Server configuration,
and distributes it to all the host controllers in the domain. Each host controller has its own configuration
file, which configures the network settings, domain membership, and defines which Application Servers
to launch, and what applications to run on them.
JBoss Application Server processes are launched by the host controller, according to the configuration
of the host controller. These Application Server processes execute applications under the management
of the domain controller. The EKM server application is executed by all JBoss instances in the domain.
A configuration called the “domain configuration” defines the configuration for the Application Servers
where hosted applications, such as EKM sever, execute.
The JBoss domain controller provides the following centralized management services for all JBoss in-
stances in the domain:
• Centralized management of the JBoss domain configuration.
• Centralized management of JBoss instances via the JBoss CLI.
• Centralized management of JBoss instances via the JBoss Web Management Interface.
Some of the management features include:
• Deployment of applications, such as the EKM Server web application.
• Access to JBoss logs.
Appendices
• Access to runtime metrics and statistics.
The role of the JBoss domain controller is to provide centralized management functionality only. It is
not necessary for the JBoss domain controller to be running for slaves to execute application servers,
run deployed applications, and serve requests. In terms of EKM functionality, if the JBoss domain con-
troller is unavailable for any reason, any slaves in the domain will continue to run (in the case of a multi-
node EKM server) and serve EKM requests. In the event of failure of a domain controller, a slave can be
promoted to domain controller to restore domain controller functionality.
14.3.2. Configuration
In JBoss domain mode, the JBoss configuration resides in the JBOSS_HOME/domain/configuration
directory. There are two configuration files for the JBoss instance: the host controller configuration, and
the domain configuration.
Host controller configuration:
JBOSS_HOME/domain/configuration/ekm-host.xml
Domain configuration (Domain Controller only):
JBOSS_HOME/domain/configuration/ekm.xml
The host controller configuration is local to each JBoss instance. To configure the host controller for a
JBoss instance, edit its host controller configuration file.
The domain configuration is global to all JBoss instances in a domain. To configure the domain config-
uration for a JBoss domain, edit the domain configuration file on the domain controller.
14.3.3. Management
Management of a JBoss domain can be performed from the JBoss Web Management Interface, or the
JBoss CLI (command-line interface). For a full discussion of JBoss management using the Web Manage-
ment Interface or CLI, refer to the JBoss Application Server (JBoss AS) documentation.
The following management tasks must be performed manually in an EKM cluster:
1. Create JBoss Management Users (p. 122)
2. Deploy the EKM Server Application (p. 124)
14.3.3.1. Create JBoss Management Users

To access the JBoss Web Management Interface, you must first create a management user that will be
used to access it. Follow these steps on the JBoss domain controller:
1. Execute the JBoss add_user script on the JBoss domain controller:

JBOSS_HOME/bin/add_user.(bat|sh)
2. Follow the prompts to create a management user for accessing the JBoss Web Management Interface.
Answer the prompts as shown in bold:
What type of user do you wish to add?
a) Management User (mgmt-users.properties)
b) Application User (application-users.properties)
(a): a
Enter the details of the new user to add.

Using realm 'ManagementRealm' as discovered from the existing property files.
Username : admin
User 'admin' already exists and is enabled, would you like to...
a) Update the existing user password and roles
b) Disable the existing user
c) Type a new username
(a): a
Password recommendations are listed below. To modify these restrictions edit the
add-user.properties configuration file.
- The password should not be one of the following restricted values {root, admin, administrator}
- The password should contain at least 8 characters, 1 alphabetic character(s),
1 digit(s), 1 non-alphanumeric symbol(s)
- The password should be different from the username
Password :
Re-enter Password :
What groups do you want this user to belong to? (Please enter a comma separated list,
or leave blank for none)[ ]:
Updated user 'admin' to file
'/home/ekm/node1/v170/programs/wildfly-8.2.0.Final/standalone/configuration/mgmt-users.properties'
Updated user 'admin' to file
'/home/ekm/node1/v170/programs/wildfly-8.2.0.Final/domain/configuration/mgmt-users.properties'
Updated user 'admin' with groups to file
'/home/ekm/node1/v170/programs/wildfly-8.2.0.Final/standalone/configuration/mgmt-groups.properties'
Updated user 'admin' with groups to file
'/home/ekm/node1/v170/programs/wildfly-8.2.0.Final/domain/configuration/mgmt-groups.properties'
Is this new user going to be used for one AS process to connect to another AS process?
e.g. for a slave host controller connecting to the master or for a Remoting connection
for server to server EJB calls.
yes/no? n
Press any key to continue . . .
Next, you must create a management user for each JBoss slave. This management user will be used by
the JBoss slave in the domain to communicate with the domain controller. These management users
are created on the JBoss domain controller, and added to the host controller configuration on each
JBoss slave.
Repeat the following steps for each JBoss slave:
1. Execute the JBoss add_user script on the JBoss domain controller:

JBOSS_HOME/bin/add_user.(bat|sh)
2. Follow the prompts to create a management user for the JBoss slave. The example below demonstrates
creating a management user named node2. Answer the prompts as shown in bold:
What type of user do you wish to add?
a) Management User (mgmt-users.properties)
b) Application User (application-users.properties)
(a): a
Enter the details of the new user to add.

Using realm 'ManagementRealm' as discovered from the existing property files.
Username : node2
Password recommendations are listed below. To modify these restrictions edit the
add-user.properties configuration file.
- The password should not be one of the following restricted values {root, admin, administrator}
- The password should contain at least 8 characters, 1 alphabetic character(s), 1 digit(s),
1 non-alphanumeric symbol(s)
- The password should be different from the username
Password :
Re-enter Password :
What groups do you want this user to belong to? (Please enter a comma separated list,
or leave blank for none)[ ]:
About to add user 'node2' for realm 'ManagementRealm'
Is this correct yes/no? y
Added user 'node2' to file
'/home/ekm/node1/v170/programs/wildfly-8.2.0.Final/standalone/configuration/mgmt-users.properties'
Appendices
Added user 'node2' to file

'/home/ekm/node1/v170/programs/wildfly-8.2.0.Final/domain/configuration/mgmt-users.properties'
Added user 'node2' with groups to file
'/home/ekm/node1/v170/programs/wildfly-8.2.0.Final/standalone/configuration/mgmt-groups.properties'
Added user 'node2' with groups to file
'/home/ekm/node1/v170/programs/wildfly-8.2.0.Final/domain/configuration/mgmt-groups.properties'
Is this new user going to be used for one AS process to connect to another AS process?
e.g. for a slave host controller connecting to the master or for a Remoting connection
for server to server EJB calls.
yes/no? y
To represent the user add the following to the server-identities definition
<secret value="bm9kZTIhMTIz"/>
3. On the JBoss slave, add the management user to the host controller configuration. The management user
is added as shown in bold:
<management>
<security-realms>
<security-realm name="ManagementRealm">
<server-identities>
14.3.3.2. Deploy the EKM Server Application

The final step to configuring EKM to run on a JBoss domain is to deploy the EKM Server application to
the domain. This can be done either through the JBoss Web Management Interface, or through the
JBoss CLI (command-line interface). The JBoss CLI may be executed in either interactive or scripted
mode.
Prerequisites:
To deploy the EKM Server application to the domain using either the JBoss Web Management Interface
or the JBoss CLI, perform these prerequisite steps:
Note
The EKM .WAR file is found at the following location: EKM_HOME/ekm-17.0.war
1. Start EKM on each EKM cluster node. This will start the host controller (and process controller) on each
JBoss instance.
The JBoss slaves register themselves with the JBoss domain controller, as shown in the logs below:
JBoss domain controller (node1):

[Host Controller] 22:16:52,256 INFO [org.jboss.as.domain] (Host Controller Service
Threads - 3) JBAS010918: Registered remote slave host "node2", WildFly 8.2.0.Final "Tweek"
JBoss slave (node2):

[Host Controller] 22:16:54,933 INFO [org.jboss.as.host.controller]
(server-registration-threads - 1) JBAS010919: Registering server node2
JBoss Web Management Interface:
Follow these steps to deploy the EKM Server application to the JBoss domain using the JBoss Web
Management Interface:
1. Log into the JBoss Web Management Interface on the JBoss domain controller1.
http://node1.mycompany.com:9990
Log in using the credentials of the management user you configured for accessing the JBoss Web
Management Interface.
2. Select the Deployments tab.
3. In the Content Repository tab, click Add to add the EKM .WAR file as a deployment. You will need to
access a copy of the EKM .WAR file that is installed on the EKM server, from the system running the browser
you are using to access the JBoss Web Management Interface.
a. The Create Deployment dialog box opens.
b. In the Managed tab, click Browse and browse to the EKM .WAR file.
c. In the Managed tab, verify the deployment names (no changes are required) and click Save to create
the deployment.
4. In the Content Repository tab, click Assign to assign the EKM .WAR file deployment to the EKM cluster.
a. The Select server groups dialog box opens.
b. Select the Assign check box to assign the EKM .WAR file deployment to the server group: ekm-
server-group
The Enable check box for the EKM .WAR file deployment should also be selected.
c. Click Save to deploy the EKM .WAR file.
The EKM Server application will now start on all EKM cluster nodes. Watch the JBoss logs on each EKM
cluster node to make sure that the EKM Server application starts correctly.
JBoss CLI (Interactive):
Follow these steps to deploy the EKM server application to the JBoss domain using the JBoss CLI
(command-line interface) in interactive mode:
1. Locate the JBoss CLI launch script on the JBoss domain controller:
JBOSS_HOME/bin/jboss-cli.(bat|sh)
Use the JBoss CLI launch script to connect to the JBoss CLI on the management network interface
and port on the JBoss domain controller (marked in bold), for example2:
jboss-cli.sh –c –controller=192.168.1.3:9999
Once connected to the JBoss CLI, you will see a prompt where you can enter JBoss CLI commands:
1
The port number used to connect to the JBoss Web Management Interface is subject to change according to the JBoss port offset used.
See Appendix E: Resolving Network Port Conflicts (p. 129).
2
The port number used to connect to the JBoss CLI is subject to change according to the JBoss port offset used. See Appendix E:
Resolving Network Port Conflicts (p. 129).
Appendices
[domain@192.168.1.3:9999 /]
2. Deploy the EKM .WAR file to the server group: ekm-server-group, substituting the full path to the
EKM .WAR file (marked in bold) in the example below:
[domain@192.168.1.3:9999 /] deploy EKM_HOME/ekm-17.0.war --server-groups=ekm-server-group
The EKM Server application will now start on all EKM cluster nodes. Watch the JBoss logs on each
EKM cluster node to make sure that the EKM Server application starts correctly.
JBoss CLI (Script):
In addition to interactive mode, JBoss CLI can execute CLI commands from a script file. The steps above
could be accomplished equivalently by calling the JBoss CLI launch script and providing a CLI script file
as an argument.
In the following examples, the JBoss CLI launch script is called from a small helper script, and executes
JBoss CLI commands stored in a CLI script file.
In these examples, values marked in bold must be modified to match your EKM server installation.
Create both files in the same directory on the EKM primary cluster node.
Linux:
deploy-ekm.sh:
#!/bin/sh
SCRIPTDIR=$(cd `dirname $0` && pwd)
#Set these variables to match your EKM server

EKM_ROOT=/home/ekm
EKM_NODE_ROOT=/home/ekm/node1
#Do not modify below this line

EKM_ROOT170=$EKM_ROOT/v170
EKM_NODE_ROOT170=$EKM_NODE_ROOT/v170
export JBOSS_HOME=$EKM_NODE_ROOT170/programs/wildfly-8.2.0.Final
export JAVA_HOME=$EKM_ROOT170/programs/jdk1.8.0_40
$JBOSS_HOME/bin/jboss-cli.sh --file=$SCRIPTDIR/deploy-ekm.txt
deploy-ekm.txt:
connect 192.168.1.3:9999
deploy /home/ekm/v170/ekm-server/ekm-17.0.war --server-groups=ekm-server-group
Windows:
deploy-ekm.cmd:
@echo off
rem Set these variables to match your EKM server
set EKM_ROOT=\\server\share\ekm
set EKM_NODE_ROOT=c:\ekm\node1
rem Do not modify below this line

set EKM_ROOT170=%EKM_ROOT%\v170
set EKM_NODE_ROOT170=%EKM_NODE_ROOT%\v170
set JBOSS_HOME=%EKM_NODE_ROOT170%\programs\wildfly-8.2.0.Final
set JAVA_HOME=%EKM_ROOT170%\programs\jdk1.8.0_40
call %JBOSS_HOME%\bin\jboss-cli.bat --file=%%~dp0\deploy-ekm.txt
deploy-ekm.txt:
connect 192.168.1.3:9999
deploy c:\ekm\v170\ekm-server\ekm-17.0.war --server-groups=ekm-server-group
Note
The JBoss CLI “deploy” command does not currently support Windows UNC paths. You must
provide a local file system (LFS) path for the EKM .WAR file.
14.3.4. JBoss Domain Controller – Failure and Promotion

In the event of failure of the JBoss domain controller, any JBoss slave can be manually promoted to
assume the role of domain controller. Promotion of slave to domain controller is a manual process –
automatic failover of the domain controller role is not currently supported in JBoss.
To promote a slave to domain controller, follow these steps on one cluster node:
1. Stop the EKM cluster node.
2. Edit the JBoss host controller configuration (see Appendix C: JBoss Domain Mode and Configuration (p. 120)).
a. In the domain-controller element, replace the remote element (shown in bold):

<domain-controller>
<remote host="192.168.1.3" port="${jboss.domain.master.port:9999}"
security-realm="ManagementRealm" />
</domain-controller>
with a local element (shown in bold):

<domain-controller>
<local />
b. Under the security-realms element, remove the management user defined for this node (shown
in bold):
<management>
<security-realms>
<security-realm name="ManagementRealm">
<server-identities>
3. Locate the cached domain configuration and activate it. The cached domain configuration file is:
JBOSS_HOME/domain/configuration/domain.cached-remote.xml
Activate the domain configuration by renaming this file to: ekm.xml
4. Create management users on the new domain controller cluster node, following the instructions in
Management (p. 122), with these modifications:
a. Create the admin user for accessing the JBoss Web Management Interface.
b. For each slave cluster node, create a management user for the node.
Appendices
Save the output of the add-user.(bat|sh) script and note which user (cluster node) it is
for. Specifically, you will need the secret element for the user, for example:
If the slave cluster node is stopped, add the management user for the cluster node to the host
controller configuration on the slave node as instructed in Management (p. 122).
If the slave cluster node is running, you will add the management user for the cluster node
later.
5. Start the EKM cluster node.
The cluster node will now be running as a domain controller. The remaining slave cluster nodes must
now be reconfigured to recognize the new domain controller.
On each slave cluster node, follow these steps:
2. Edit the JBoss host controller configuration (see Appendix C: JBoss Domain Mode and Configuration (p. 120)):
a. In the domain-controller element, update the remote element (shown in bold) to point to
the IP address and port of the new domain controller:
<domain-controller>
b. If you have not already done so in a previous step, add the management user for the cluster node.
The JBoss slaves should register with the new domain controller during startup.
14.4. Appendix D: Email Configuration

The configuration of the email server is performed by the ANSYS EKM Server product installation. If
necessary, the email server configuration can be changed after setup by following the instructions in
this section. To change the email server configuration, perform the following steps:
1. On each EKM cluster node, stop the EKM server.
2. Edit the JBoss domain configuration (see Appendix C: JBoss Domain Mode and Configuration (p. 120)).
3. Find the socket-binding-groups configuration element:

<socket-binding-groups>
4. Find the socket-binding-group element whose name is ha-sockets:

<socket-binding-group name="ha-sockets" default-interface="public">
5. Find the outbound-socket-binding child element whose name is mail-smtp:
Appendix E: Resolving Network Port Conflicts
<outbound-socket-binding name="mail-smtp">
<remote-destination host="smtp.mycompany.com" port="25" />
</outbound-socket-binding>
6. In the remote-destination child element, modify the host property (shown above in bold) to set
the SMTP server.
7. On each EKM cluster node, start the EKM server.
14.5. Appendix E: Resolving Network Port Conflicts

EKM cluster nodes use the JBoss application server. JBoss uses multiple TCP/IP network ports to provide
network services. Some of these ports may conflict with other software or services on the server host
where EKM is installed. In particular, network port conflicts are likely to occur if another instance of
JBoss is installed on the server host where EKM is installed. This scenario arises when multiple EKM
cluster nodes are installed on the same server host.
In the event of network port conflicts, it is possible to conveniently change all network ports used by
JBoss with a single configuration change. This is done by changing the port offset used by JBoss.
JBoss uses socket binding groups to define and control the network port assignments of services within
JBoss. Socket binding groups make it possible to reconfigure all network ports used by JBoss at once
by assigning a port offset to the socket binding group. The port offset is a numerical offset that is applied
to the base value of a network port to determine its runtime value. The default value of the port offset
is 0, which means runtime values of network port numbers is not changed. A port offset of 100 would
increment all network port numbers by 100.
Note
When changing the port offset, you should use increments of 100, such as 100, 200, 300 and
so on.
To set the JBoss port offset on an EKM cluster node:
1. Edit EKM_NODE_ROOT170/bin/ekm_env.(cmd|sh) and set the value of the JBOSS_PORT_OFFSET

environment variable (value shown in bold).
Windows:
rem JBoss socket binding group port offset
set JBOSS_PORT_OFFSET=0
Linux:
# JBoss socket binding group port offset
export JBOSS_PORT_OFFSET=0
2. (Windows only) Edit JBOSS_HOME/domain/configuration/wrapper.conf and set the value of

the JBOSS_PORT_OFFSET environment variable (value shown in bold):
set.JBOSS_PORT_OFFSET=0
3. If the EKM cluster node whose JBoss port offset is being changed is the JBoss domain controller, it is ne-
cessary to change the JBoss configuration of each slave. Follow these steps on each slave:
Appendices
a. Edit the JBoss host controller configuration (see Appendix C: JBoss Domain Mode and Configura-
tion (p. 120)).
b. Find the domain-controller element, then find its remote child element.
c. Modify the port attribute to reflect the updated value of the JBoss management native port on the
JBoss domain controller:
<remote host="192.168.1.3" port="${jboss.domain.master.port:9999}" security-realm="ManagementRealm" />
For example, if the JBoss port offset was changed from 0 to 100 on the JBoss domain controller,
each slave would be modified as follows:
<remote host="192.168.1.3" port="${jboss.domain.master.port:10099}" security-realm="ManagementRealm" />
4. If the EKM server is a single-node server, edit EKM_HOME/conf/ekm.xml and update the value of ek-
mUrl (shown in bold) to the new URL for EKM:
<ekmUrl>http://ekm.mycompany.com:8080/ekm</ekmUrl>
Old URL: http://ekm.mycompany.com:8080/ekm
New URL: http://ekm.mycompany.com:NNNN/ekm
where NNNN is the new EKM server HTTP port.
If the EKM server is a multi-node server, ekmUrl is set to the URL of the front-end webserver,
which is not affected by changes to the JBoss port offset of the EKM cluster nodes.
5. Refer to Appendix I: Updating EKM Server Objects (p. 134) and update any server objects in EKM workspaces
on remote EKM servers that refer to this EKM server.
14.6. Appendix F: Changing the JBoss HTTP Port

This section provides instructions for changing the JBoss HTTP port. This content applies to single-node
EKM servers that do not use a front-end webserver. In this configuration, clients connect directly to the
HTTP port of JBoss to access EKM.
For instructions on changing the HTTP port of a front-end web server, refer to Installing a Front-End
Web Server (p. 43).
By default, JBoss listens on port 8080/TCP for incoming HTTP connections. However, it is sometimes
necessary or desired to change this to another port, such as 80/TCP. To change the HTTP port, follow
the instructions in this section.
Note
On Linux systems, ports below 1024 are called “privileged ports.” Root privileges are required
for a program to open these ports. Windows does not enforce this restriction.
Some firewalls and security products may process or alter traffic whose destination port is
port 80 (HTTP) in ways that may cause EKM to function incorrectly. If you decide to configure
the EKM server, or a front-end web server connected to the EKM server, to listen on port 80
Appendix G: Setting the HTTP Session Timeout
and experience difficulties using the EKM server, it may be necessary to configure the EKM
server or front-end web server to use another port, such as 8080.
To change the HTTP port under JBoss, follow these steps:
3. Find the socket-binding-groups configuration element:

4. Find the socket-binding-group element whose name is ha-sockets:

5. Find the socket-binding child element whose name is http:

<socket-binding name="http" port="${jboss.http.port:8080}"/>
6. Modify the port number (8080), shown above in bold, to change the value to the desired port number.
Note
The HTTP port number set here is adjusted by the port offset as described in Appendix
E: Resolving Network Port Conflicts (p. 129).
7. Edit EKM_HOME/conf/ekm.xml and update the value of ekmUrl (shown in bold) to the new URL for
EKM:
<ekmUrl>http://ekm.mycompany.com:8080/ekm</ekmUrl>
Old URL: http://ekm.mycompany.com:8080/ekm
New URL: http://ekm.mycompany.com:NNNN/ekm
where NNNN is the new EKM server HTTP port.
9. Refer to Appendix I: Updating EKM Server Objects (p. 134) and update any server objects in EKM workspaces
on remote EKM servers that refer to this EKM server.
14.7. Appendix G: Setting the HTTP Session Timeout

When a user connects to the EKM server through a client, such as the web client, an HTTP session is
established for the user on the EKM server. To prevent inactive sessions from staying open for too long
and consuming resources unnecessarily, the EKM server will time out inactive HTTP sessions after a
predefined period of idle time. When the HTTP session times out, the EKM session will also be invalidated,
requiring the user to sign in again. The HTTP session timeout period is governed by a setting in the
EKM server configuration, and is set to the value you provide in the ANSYS EKM Server product install-
Appendices
ation. You can also adjust the HTTP session timeout of the EKM server manually after installation by
following these instructions:
2. On the primary cluster node, edit EKM_HOME/conf/ekm.xml and update the value of session-
Timeout (shown in bold) to the desired HTTP session timeout, in minutes:
<sessionTimeout>30</sessionTimeout>
14.8. Appendix H: Changing the MySQL Database Server Port

This appendix applies to EKM servers using the MySQL database server.
By default, the MySQL database server listens for client connections on TCP port 3306. If the default
port is already used by another process, it is necessary to change the port used by the MySQL database
server. If this port is changed, it is also necessary to reconfigure EKM to use the new port.
To change the MySQL database server port:
2. Stop the database server (MySQL).
3. Perform the following modifications to the MySQL and EKM configuration:
MySQL Configuration:
Edit MYSQL_HOME/my.(cnf|ini) and update all occurrences of the port setting to the new
port number (value shown below in bold).
[client]
port=3306
user=root
password=root123
[mysqladmin]
port=3306
user=root
password=root123
[mysqld]
port=3306
default_storage_engine=INNODB
transaction_isolation=READ-COMMITTED
max_allowed_packet=128m
EKM Configuration:
Update the MySQL database server port in the JBoss domain configuration (see Appendix C:
JBoss Domain Mode and Configuration (p. 120)):
a. Find the datasources subsystem configuration element:

<subsystem xmlns="urn:jboss:domain:datasources:2.0">
Appendix I: Configuring Windows Services (Windows Only)
b. Find the datasources child element, then find its datasource child element whose pool-
name attribute value is ekmds:
<datasource jndi-name="java:jboss/datasources/ekmds"
pool-name="ekmds" enabled="true" use-java-context="true">
<connection-url>jdbc:mysql://localhost:3306/ekm</connection-url>
<driver>org.mariadb.jdbc</driver>
<transaction-isolation>TRANSACTION_READ_COMMITTED</transaction-isolation>
...
...
</datasource>
c. Modify the value of the connection-url element (shown above in bold) to the new MySQL
JDBC URL for the MySQL database server, to reflect the new port number.
MySQL JDBC URLs follow the form:
jdbc:mysql://[host][:port]/[database]
where:
host: the database server host. If host is not specified, 127.0.0.1 (localhost) is used.
port: the database server port. If port is not specified, the default port of 3306 is used.
database: the name of the database to connect to. The default name is ekm.
4. Start the cluster database server (MySQL).
14.9. Appendix I: Configuring Windows Services (Windows Only)

EKM servers can be registered and run as Windows services.
When run in console mode, environment variables and other parameters required by EKM are set in
the control scripts located in EKM_NODE_ROOT170/bin and are evaluated when the EKM console
mode control scripts are executed.
When run in service mode, environment variables and other parameters required by EKM are set and
evaluated in the manner described below:
EKM servers use a program called Java Service Wrapper to register and run the JBoss application server
as a Windows service. EKM servers also use the service registration and execution capability of the
MySQL database server to register and run MySQL as a Windows service, where applicable.
The environment variables and other parameters used by the EKM service, which runs the JBoss applic-
ation server, are set in the configuration file for Java Service Wrapper. This file is named wrapper.conf
and is located at the following path:
wrapper.conf contains settings for the Java Virtual Machine that is executed by Java Service Wrapper.
It also contains environment variable settings for the program that it launches—in this case, the JBoss
application server where the EKM server application is deployed. The environment variables and para-
meters in this file include settings for EKM that correspond to the settings in the console mode control
scripts in EKM_NODE_ROOT170/bin, including ekm_env.cmd and ekm_start.cmd. Java Service
Appendices
Wrapper does not use the control scripts; all environment variables and parameters that apply to EKM
running in service mode are defined in wrapper.conf itself.
Most settings in wrapper.conf are processed each time the EKM service starts, and do not require
re-registration of the EKM service to take effect. A few settings are processed only when the service is
registered – these are limited to items whose parameter names begin with wrapper.ntservice –
these have to do with the Windows service definition itself and generally do not need to be changed.
If you need to modify any environment variables or parameters for the EKM service, follow these steps:
1. Stop the EKM service.
2. Edit JBOSS_HOME/domain/configuration/wrapper.conf
3. Start the EKM service.
Note
The environment variable settings in wrapper.conf follow a format that is specific to the
Java Service Wrapper. The format is:
set.VARIABLE=VALUE
Do not remove the period between the word “set” and the environment variable name. See
the Java Service Wrapper manual for details.
14.10. Appendix J: Updating EKM Server Objects

EKM servers are represented in EKM workspaces by EKM Server objects. Each Server object contains the
hostname of the EKM server, and the port (port number) that the EKM server is configured to listen for
client connections on.
In a distributed deployment of EKM, Server objects are used to locate other EKM servers. Whenever a
change is made to either the hostname or port number of an EKM server, it is necessary to visit any
remote EKM servers and workspaces that have Server objects defined for this server, and update those
Server objects.
The port number that an EKM server listens on can change in a number of scenarios, including:
• The port number of the front-end web server is changed (if applicable).
• The HTTP port is changed as per Appendix E: Resolving Network Port Conflicts (p. 129)
• The HTTP port is changed as per Appendix F: Changing the JBoss HTTP Port (p. 130)
For a complete discussion of Server objects, see the Administration Guide.
Appendix K: Granting Database Privileges
14.11. Appendix K: Granting Database Privileges

MySQL controls access to database privileges via a combination of username, password3, and host. By
default, the MySQL “root” user on the host where the MySQL server is running has full privileges to
create, drop and alter databases on the server.
It is necessary to manually grant database privileges on the EKM database server to the EKM server
when an existing or default MySQL database server is used.
The connection information that the EKM server needs to connect to the EKM database server is provided
during installation, and includes the hostname of the EKM database server, the port number to connect
on, and the MySQL username and password that the EKM server will use when connecting to the EKM
database server.
The EKM database server must grant full database privileges to each EKM cluster node. Client connections
are defined by username/password/host, and privileges are granted to client connections based on
entries in an internal MySQL database that defines the privileges granted to matching client connections.
On the cluster database server, for each cluster node, grant full database permissions for client connec-
tions matching:
• Username: EKM database server username specified during setup of the EKM cluster node.
• Password: EKM database server password specified during setup of the EKM cluster node.
• Hostname: FQDN (fully-qualified domain name) of the host where the cluster node is set up.
To grant full database privileges, follow the instructions below:
1. On the EKM database server, start a MySQL client session on the MySQL database server.
For an EKM database server set up using the ANSYS EKM Server product installation, a MySQL
client session can be started by running the control script: EKM-
DB_ROOT/bin/mysql.(cmd|sh)
2. Grant full database privileges to the connections specified in the instructions above. The example
below demonstrates granting full database privileges to connections matching:
username=root, password=root123, and hostname=hostname.yourdomain.com

mysql> use mysql;
Database changed
mysql> GRANT ALL PRIVILEGES ON *.* TO root@hostname.yourdomain.com

IDENTIFIED BY 'root123' WITH GRANT OPTION;
Query OK, 0 rows affected (0.00 sec)
mysql> flush privileges;

Query OK, 0 rows affected (0.00 sec)
After executing all the necessary GRANT statements, you should execute the flush priv-
ileges statement once to enable the new privileges.
3. Exit the MySQL client session.
3
These usernames and passwords are MySQL account credentials, NOT operating system or network account credentials.
Appendices
Consult the MySQL Server documentation for more information about granting database privileges,
including use of the wildcards.
14.12. Appendix L: Clearing the Repository
Important
The procedure provided in this Appendix will delete ALL EKM workspaces and data from the
EKM repository. DO NOT follow this procedure unless you intend to completely remove ALL
stored data from your EKM server.
2. On each EKM cluster node, delete all files and directories within REPOSITORIES_HOME except for the
following:
cacheStore/
repository.xml.template
3. On each EKM cluster node, delete all files and directories within REPOSITORIES_HOME/cacheStore
except for the following:
repository.xml
4. Delete the contents of the shared EKM data directory4.
5. On the EKM database server, delete and recreate the EKM database:
a. Connect to the EKM database server in console mode by running the control script: EKM-
DB_ROOT/bin/mysql.(cmd|sh)
b. Delete and recreate the EKM database by issuing the following commands in the mysql console:
drop database ekm;
create database ekm;
exit
14.13. Appendix M: Disabling HTTP Compression

This section provides instructions for disabling HTTP compression in JBoss. This content applies to
single-node EKM servers that do not use a front-end webserver, where clients connect directly to the
HTTP port of JBoss to access EKM.
41
To determine the location of the shared EKM data directory, look at the following file on one of the EKM cluster nodes: REPOSITOR-
IES_HOME/repository.xml.template
Find the DataStore element, and check the value of the path attribute (shown in bold):
<DataStore class="com.ansys.ingress.core.model.persistence.EkmFileDataStore">
<param name="path" value="/server/share/ekm/datastore" />
Appendix N: Changing the JVM Heap Size
For instructions on disabling HTTP compression in a front-end web server, refer to Installing a Front-
End Web Server (p. 43).
HTTP compression is enabled by default in JBoss. It is not necessary under normal circumstances to
disable HTTP compression, but if you need to do so, follow these instructions:
2. Edit the JBoss domain configuration (see Appendix C: JBoss Domain Mode and Configuration (p. 120)):
3. Find the undertow subsystem element, and find the server child element whose name attribute value
is default-server. Find the host child element named default-host:
<host name="default-host" alias="localhost">
4. Under the host element, comment out the filter-ref child element named gzipFilter:

5. Find the undertow subsystem element, and find the filters child element.
6. Under the filters element, comment out the gzip child element:

14.14. Appendix N: Changing the JVM Heap Size

If you encounter errors related to the memory usage of the Java Virtual Machine (JVM), such as
java.lang.OutOfMemoryError, it may be necessary to increase the maximum heap size of the
JVM.
EKM cluster nodes run JBoss in domain mode (p. 120). In domain mode, JBoss launches three JVMs, one
for each of the following processes: process controller, host controller, and an application server. To
change the JVM heap size for EKM, we must change the JVM settings of the application server process.
The JVM settings of the application server process are set in the host controller configuration.
To change the JVM heap size, follow these steps:
1. On each EKM cluster node, stop the EKM cluster node.
2. Edit the JBoss host controller configuration (see Appendix C: JBoss Domain Mode and Configuration (p. 120)).
Find the lines:
<servers>
<server name="node1" group="ekm-server-group">
<socket-bindings port-offset="${env.JBOSS_PORT_OFFSET}" />
<jvm name="default">
<heap size="256m" max-size="4096m" />
Appendices
<jvm-options>
<option value="-XX:MetaspaceSize=128m" />
<option value="-XX:MaxMetaspaceSize=512m" />
</jvm>
</server>
</servers>
3. Change the value of the max-size parameter (shown above in bold) to the desired value, in megabytes,
for the maximum heap size of the JVM.
4. On each EKM cluster node, start the EKM cluster node.
Note
It is rarely necessary to change the JVM heap settings of the JBoss process controller and
host controller processes. If necessary, these can be changed by editing the corresponding
options in the ekm_start control script, and (Windows only) the Java Service Wrapper
configuration: wrapper.conf.
14.15. Appendix O: Configuring EKM to Use Amazon S3 Data Storage

You can configure an EKM server to use the Amazon Simple Storage Service (Amazon S3) provided by
Amazon Web Services (AWS) to store repository objects. In order to use S3, you must have an AWS ac-
count.
Important
These steps must be done when the repository is clear, such as before starting EKM for the
first time, or after clearing the repository. See Appendix L: Clearing the Repository (p. 136)
for instructions on clearing the repository.
To configure EKM server to use Amazon S3, perform the following steps on each EKM cluster node:
1. Edit the file EKM_HOME/conf/aws.properties.
Specify the following values:
accesskey: Your AWS account ID

secretkey: Your AWS secret key
s3Bucket: Your AWS bucket name
s3Region: Your AWS bucket region
2. Edit the file REPOSITORIES_HOME/repository.xml.template.
Replace the content of the DataStore element with the following:

<DataStore class="org.apache.jackrabbit.aws.ext.ds.S3DataStore">
<param name="config" value="full path to aws.properties file within EKM_HOME/conf"/>
<param name="minRecordLength " value="16384"/>
<param name="cacheSize" value="68719476736"/>
<param name="cachePurgeTrigFactor" value="0.95d"/>
<param name="cachePurgeResizeFactor" value="0.85d"/>
<param name="continueOnAsyncUploadFailure" value="false"/>
<param name="concurrentUploadsThreads" value="10"/>
<param name="asyncUploadLimit" value="0"/>
Appendix P: Creating a Silent Installation File
<param name="uploadRetries" value="3"/>

</DataStore>
3. Edit the file REPOSITORIES_HOME/cacheStore/repository.xml.
Replace the content of the DataStore element with the content shown in the step above.
14.16. Appendix P: Creating a Silent Installation File

It is possible to install an EKM server using silent installation, as documented in Running a Silent Install-
ation (p. 34). In order to perform a silent installation, a silent installation file must be created. This file
is used by silent installation to set the configuration options for the EKM server, such as the server type,
base directory, and so on. All configuration options present in the graphical ANSYS EKM Server product
installation can be controlled in the silent installation file.
14.16.1. Silent Installation Options
Note
When specifying paths in the silent installation file, always use a forward slash (/) as the path
separator character, even for Windows paths. For example, C:\ekm\node1 should be
written as C:/ekm/node1.
task
Description: The setup task to run.

Required Value: setupEkmServer
ekmServer.clickWrapResponse
Description: Response to EKM click-wrap license agreement.

Required Value: I AGREE
ekmServer.installLog
Description: Directory for install log. Recommended value: set to same value as ekmServ-
er.ekmNodeRoot.
Example Value (Windows): c:/ekm/node1
Example Value (Linux): /home/ekm/node1
ekmServer.installDefaultDb
Description: Install the default MySQL database server.

Allowed Values: true, false
ekmServer.cluster
Description: Install EKM server in cluster configuration.

Required Value: true
ekmServer.clusterName
Description: The name of the EKM cluster.
Appendices
Example Value: ekmServer
ekmServer.clusterNodeId
Description: The node ID of the EKM cluster node.

Example Value: node1
ekmServer.jbossPortOffset
Description: JBoss port offset.

Example Value: 0, 100, 200, etc.
ekmServer.clusterPrimaryNode
Description: This cluster node is the primary node of the EKM cluster.
Allowed Values: true, false
ekmServer.clusterPrimaryNodeIp
Description: The IP address of the primary cluster node of the EKM cluster.
Example Value: 10.0.0.10
ekmServer.existingDbType
Description: Existing database server type.

Allowed Values: MySQL, Oracle
ekmServer.dbHostname
Description: Hostname for EKM database server.

Example Value: ekmdb.mycompany.com
Note
Set ekmServer.dbHostname when setting up EKM to use an existing database server.

Do not set ekmServer.dbHostname when installing the default MySQL database
server (that is, when ekmServer.installDefaltDb is true).
ekmServer.dbPort
Description: Port number for EKM database server.

Example Value (MySQL): 3306
Example Value (Oracle): 1521
ekmServer.dbUsername
Description: User name for EKM database server.

Example Value: root
ekmServer.dbPassword
Description: Password for EKM database server.

Example Value: root123
ekmServer.dbName
Description: Database name for EKM database server.

Example Value: ekm
ekmServer.jdbcDriverLocation
Description: JDBC driver location.

Example Value (Oracle): c:/temp/ojdbc6.jar,c:/temp/orai18n.jar
ekmServer.ekmDb
Description: Base directory for EKM database server.

Example Value (Windows): c:/ekm/mysql-5.5.41
Example Value (Linux): /home/ekm/mysql-5.5.41
Note
Set ekmServer.ekmDb when installing the default MySQL database server (that is,
when ekmServer.installDefaltDb is true).
ekmServer.ekmRoot
Description: Base directory for EKM server.

Example Value (Windows): \\server\share\ekm
Example Value (Linux): /server/share/ekm
ekmServer.ekmNodeRoot
Description: Base directory for EKM cluster node.

Example Value (Windows): c:/ekm/node1
Example Value (Linux): /home/ekm/node1
ekmServer.ekmData
Description: EKM data directory.

Example Value (Windows): \\server\share\ekm\datastore
Example Value (Linux): /server/share/ekm/datastore
ekmServer.ekmJobdata
Description: EKM job data directory.

Example Value (Windows): \\server\share\ekm\jobdata
Example Value (Linux): /server/share/ekm/jobdata
ekmServer.clusterVisibleDirs
Description: EKM cluster visible directories.

Example Value (Windows): \\server\share1,\\server\share2
Example Value (Linux): /server/share1,/server/share2
ekmServer.ekmTemp
Description: EKM temp directory.
Appendices
Example Value (Windows): c:/temp

Example Value (Linux): /tmp
ekmServer.ansysLicDir
Description: ANSYS licensing directory.

Example Value (Windows): c:/Program Files/ANSYS Inc/Shared Files/Licensing
Example Value (Linux): /ansys_inc/shared_files/licensing
ekmServer.ekmServerAcctUsernameWin
Description: EKM server account.

Example Value: ekm
Note
Windows only.
ekmServer.ekmServerAcctDomainWin
Description: EKM server account domain.

Example Value: mycompany.com
Note
Windows only.
ekmServer.designatedRootUser
Description: The primary administrator for an EKM workspace.

Example Value: ekmadmin
ekmServer.sessionTimeout
Description: EKM server session timeout.

Example Value: 30
ekmServer.smtpServerHostname
Description: SMTP server hostname.

Example Value: smtp.mycompany.com
ekmServer.rsmWindowsDomain
Description: RSM windows domain.

Example Value: MYCOMPANY etc.
Note
Windows only.
14.16.2. Example Silent Installation Files

EKM primary cluster node with default MySQL database server (Windows):
task=setupEkmServer
ekmServer.clickWrapResponse=I AGREE
ekmServer.installLog=c:/ekm/node1
ekmServer.cluster=true
ekmServer.clusterName=ekmserver
ekmServer.clusterNodeId=node1
ekmServer.clusterPrimaryNode=true
ekmServer.jbossPortOffset=0
ekmServer.installDefaultDb=true
ekmServer.ekmDb=\\\\server\\share\\ekm\\mysql-5.5.41
ekmServer.dbPort=3306
ekmServer.dbPassword=root123
ekmServer.ekmRoot=\\\\server\\share\\ekm
ekmServer.ekmNodeRoot=c:/ekm/node1
ekmServer.ekmData=\\\\server\\share\\ekm\\datastore
ekmServer.ekmJobdata=\\\\server\\share\\ekm\\jobdata
ekmServer.clusterVisibleDirs=\\\\cluster\\share1,\\\\cluster\\share2
ekmServer.ekmTemp=c:/ekm/temp
ekmServer.ansysLicDir=C:/Program Files/ANSYS Inc/Shared Files/Licensing
ekmServer.ekmServerAcctUsernameWin=ekm
ekmServer.ekmServerAcctDomainWin=mycompany.com
ekmServer.designatedRootUser=ekmadmin
ekmServer.sessionTimeout=30
ekmServer.smtpServerHostname=smtp.mycompany.com
ekmServer.rsmWindowsDomain=MYCOMPANY
EKM primary cluster node with existing MySQL database server (Windows):
task=setupEkmServer
ekmServer.installDefaultDb=false
ekmServer.existingDbType=MySQL
ekmServer.dbHostname=192.168.1.2
ekmServer.dbUsername=root
ekmServer.dbName=ekm
ekmServer.ekmData=\\\\server\\share\\ekm\\datastore
ekmServer.ekmJobdata=\\\\server\\share\\ekm\\jobdata
ekmServer.clusterVisibleDirs=\\\\cluster\\share1,\\\\cluster\\share2
ekmServer.ansysLicDir=C:/Program Files/ANSYS Inc/Shared Files/Licensing
ekmServer.ekmServerAcctUsernameWin=ekm
ekmServer.ekmServerAcctDomainWin=mycompany.com
ekmServer.rsmWindowsDomain=MYCOMPANY
EKM non-primary cluster node (Windows):

task=setupEkmServer
ekmServer.clusterPrimaryNode=false
Appendices
ekmServer.clusterPrimaryNodeIp=192.168.1.3
EKM primary cluster node with default MySQL database server (Linux):
task=setupEkmServer
ekmServer.installLog=/home/ekm/node1
ekmServer.installDefaultDb=true
ekmServer.ekmDb=/server/share/ekm/mysql-5.5.41
ekmServer.ekmRoot=/server/share/ekm
ekmServer.ekmNodeRoot=/home/ekm/node1
ekmServer.ekmData=/server/share/ekm/datastore
ekmServer.ekmJobdata=/server/share/ekm/jobdata
ekmServer.clusterVisibleDirs=/cluster/share1,/cluster/share2
ekmServer.ekmTemp=/tmp
ekmServer.ansysLicDir=/ansys_inc/shared_files/licensing
EKM non-primary cluster node (Linux):

task=setupEkmServer
ekmServer.clusterPrimaryNode=false
ekmServer.clusterPrimaryNodeIp=192.168.1.3
EKM primary cluster node with existing Oracle database server (Linux):
task=setupEkmServer
ekmServer.existingDbType=Oracle
ekmServer.dbHostname=localhost
ekmServer.dbUsername=ekm
ekmServer.dbPassword=ekm123
ekmServer.dbName=xe
ekmServer.ekmData=/server/share/ekm/datastore
ekmServer.ekmJobdata=/server/share/ekm/jobdata
ekmServer.clusterVisibleDirs=/cluster/share1,/cluster/share2
ekmServer.ansysLicDir=/ansys_inc/shared_files/licensing
Appendix Q: EKM Cluster Network Configuration
ekmServer.jdbcDriverLocation=/tmp/ojdbc6.jar,/tmp/orai18n.jar
14.17. Appendix Q: EKM Cluster Network Configuration

EKM uses JGroups clustering software to provide clustering capabilities. The configuration of JGroups
is set in the JBoss configuration (p. 120).
JGroups Configuration
JGroups configuration is highly specialized, and should only be performed by IT professionals with ad-
vanced networking experience. It is not necessary under normal circumstances to edit the JGroups
configuration, but if you need to do so, the information in this section will help you.
JGroups configuration is based upon “stacks” which define the set of network protocols and configuration
settings that are used by JGroups for network communications. JGroups stacks are defined in the domain
configuration (ekm.xml), in the jgroups configuration element, as shown below (portions omitted):
<subsystem xmlns="urn:jboss:domain:jgroups:2.0" default-stack="udp">
...
<stack name="udp-ekm">
<transport type="UDP" socket-binding="jgroups-udp-ekm"/>
...
The JGroups stack used by EKM is specified by a system property in the host controller configuration
(ekm-host.xml), as shown below (portions omitted). The default stack used by EKM is udp-ekm:
<servers>
<server name="node1" group="ekm-server-group">
<socket-bindings port-offset="${env.JBOSS_PORT_OFFSET}" />
<system-properties>
...
<property name="ekm.jgroups.stack" value="udp-ekm" />
JGroups stacks may contain configuration settings that refer to socket bindings that are defined in the
socket-bindings configuration element:
...
<socket-binding name="jgroups-udp-ekm" port="55201"
multicast-address="${jboss.default.multicast.
address:230.0.0.4}" multicast-port="45689" />
<socket-binding name="jgroups-udp-fd-ekm" port="54201" />
To edit the JGroups configuration for EKM, follow these steps:
3. Configure the JGroups stack and/or socket bindings used by EKM according to your needs.
Appendices
You may also define a new JGroups stack for use by EKM, and configure EKM to use this stack by
changing the value of the ekm.jgroups.stack system property in the host controller configur-
ation.
Important
The JBoss configuration contains additional JGroups stack definitions and socket-bindings
which are used by the JBoss application server for other services. Be careful to change
only the JGroups stack and associated socket bindings used by EKM.
JGroups Multicast Configuration

The default configuration of JGroups for EKM uses UDP multicast for cluster network communications.
If more than one EKM server5 is installed on the same LAN, it may be necessary to configure the UDP
multicast address and/or port uniquely for each EKM server, so that each EKM server only receives UDP
multicast traffic destined for it, and not traffic destined for other EKM servers.
To change the JGroups multicast configuration of the EKM server:
1. Follow the steps in JGroups Configuration (p. 145), with these additional instructions:
2. In step 3, configure the socket-binding named jgroups-udp-ekm. Change the value of the mul-
ticast-port attribute to a unique port number that is not used by any other EKM servers on the same
LAN.
14.18. Appendix R: Configuring the MySQL Connector/J JDBC Driver

When MySQL is selected as the database server during ANSYS EKM Server product installation, the
MySQL-compatible MariaDB driver is installed by default.
For production usage of EKM, it is recommended to download and configure the MySQL Connector/J
driver. This driver can be downloaded from the following URL:
http://dev.mysql.com/downloads/connector/j/
To configure the MySQL Connector/J driver, perform the following steps:
2. Create a JBoss module for MySQL Connector/J:
a. Create the module directory:
JBOSS_HOME/modules/com/mysql/jdbc/main
b. Copy the MySQL Connector/J driver to the module directory. The driver is a .JAR file; for example:
mysql-connector-java-5.1.37-bin.jar
5
An EKM server includes one or more EKM cluster nodes with the same cluster name.
Appendix S: Changing the EKM Cluster Name
c. Create the module descriptor file called module.xml in the module directory. The module descriptor
file should contain the following content. Substitute the actual filename of the MySQL Connector/J
driver you downloaded for the filename shown in bold in the example below:
<?xml version="1.0" encoding="UTF-8"?>
<module xmlns="urn:jboss:module:1.1" name="com.mysql.jdbc">
<resources>
<resource-root path="mysql-connector-java-5.1.37-bin.jar" />
</resources>
<dependencies>
<module name="javax.api" />
<module name="javax.transaction.api" />
</dependencies>
</module>
Perform the following additional steps on the JBoss domain controller:
2. Find the datasources subsystem configuration element:

<subsystem xmlns="urn:jboss:domain:datasources:2.0">
3. Find the datasources child element, then find its datasources child element whose pool-name
attribute value is ekmds:
<datasource jndi-name="java:jboss/datasources/ekmds" pool-name="ekmds" enabled="true"
use-java-context="true">
Change the value of the driver child element from:

<driver>org.mariadb.jdbc</driver>
to:
<driver>com.mysql.jdbc</driver>
4. Find the drivers child element, and replace the driver child element for the MariaDB driver:
<driver name="org.mariadb.jdbc" module="org.mariadb.jdbc">
<driver-class>org.mariadb.jdbc.Driver</driver-class>
<datasource-class>org.mariadb.jdbc.MysqlDataSource</datasource-class>
</driver>
with a driver child element for the MySQL Connector/J driver:

<driver name="com.mysql.jdbc" module="com.mysql.jdbc">
<driver-class>com.mysql.jdbc.Driver</driver-class>
<datasource-class>com.mysql.jdbc.jdbc2.optional.MysqlDataSource</datasource-class>
</driver>
Perform the following steps on each EKM cluster node:
14.19. Appendix S: Changing the EKM Cluster Name

Recall from Naming the Cluster and Cluster Nodes (p. 27) that each EKM server on the same LAN must
have a unique cluster name. If you encounter a situation where you need to change the cluster name
of an EKM server, follow these steps:
Appendices
1. Edit the control script: EKM_ROOT170/bin/ekm_env.(cmd|sh)
Change the value of the EKM_CLUSTER_NAME environment variable to the new EKM cluster name:
Windows:
rem EKM Cluster Name
set EKM_CLUSTER_NAME=ekmservernewname
Linux:
# EKM Cluster Name
export EKM_CLUSTER_NAME=ekmservernewname
2. (Windows only) On each cluster node, edit the Java Service Wrapper configuration:
Change the value of the EKM_CLUSTER_NAME environment variable to the new EKM cluster name:
set.EKM_CLUSTER_NAME=ekmservernewname
3. On each cluster node, follow the instructions to rename the cluster node service as necessary to reflect
the new cluster name, as described in Service Names (p. 89).
4. On the cluster database server, follow the instructions to rename the cluster database service as necessary
to reflect the new cluster name, as described in Service Names (p. 89).
5. Rename any other EKM services as necessary to reflect the new cluster name.
14.20. Appendix T: Changing an EKM Cluster Node IP Address

When an EKM cluster node is installed using ANSYS EKM Server product installation, the EKM cluster
node is configured to use one of the non-loopback IP addresses on the server host. If the IP address of
the server host changes, or the server host has multiple IP addresses and you wish to configure the
EKM cluster node to use a different one than was configured during product installation, you may
change the IP address of the cluster node by following these steps:
2. Edit the control script: EKM_NODE_ROOT170/bin/ekm_env.(cmd|sh)
Change the values of the JBOSS_PUBLIC_IP and JBOSS_MANAGEMENT_IP environment variables

to the new IP address, as show in bold:
Windows:
rem JBoss Public IP
set JBOSS_PUBLIC_IP=192.168.1.5
rem JBoss Management IP

set JBOSS_MANAGEMENT_IP=192.168.1.5
Linux:
# JBoss Public IP
export JBOSS_PUBLIC_IP=192.168.1.5
Appendix U: Troubleshooting
# JBoss Management IP
export JBOSS_MANAGEMENT_IP=192.168.1.5
3. (Windows only) Edit the Java Service Wrapper configuration:
Change the values of the JBOSS_PUBLIC_IP and JBOSS_MANAGEMENT_IP environment variables

to the new IP address, as shown in bold:
set.JBOSS_PUBLIC_IP=192.168.1.5
set.JBOSS_MANAGEMENT_IP=192.168.1.5
5. If the EKM cluster node whose IP address you changed is the primary node (p. viii), you must complete
the following steps on each non-primary node (p. viii):
a. Stop the EKM cluster node.
b. Edit the JBoss host-controller configuration (see Appendix C: JBoss Domain Mode and Configura-
tion (p. 120)).
c. Under the domain-controller element, edit the remote element and set the value of the host
attribute to the new IP address of the primary node:
<domain-controller>
d. Start the EKM cluster node.
14.21. Appendix U: Troubleshooting

Information provided below will help guide you when troubleshooting problems that may arise during
or after EKM setup.
EKM Server Fails to Start

1. You have started JBoss without starting the MySQL database server.
Solution: Stop the EKM server (JBoss), start the MySQL database server, then start the EKM server
(JBoss) again.
2. EKM was abnormally terminated. EKM fails to start when you try to start EKM again.
Solution: When the EKM server starts up, it creates a .lock file in each repository directory under
REPOSITORIES_HOME. The lock files are automatically deleted when EKM is normally terminated.
If EKM is abnormally terminated, you may need to manually delete a lock file in one or more repos-
itory directories under REPOSITORIES_HOME and restart EKM.
3. EKM server has run out of memory.
Appendices
Solution: Increase the JVM Heap Size for the EKM server (JBoss) by following the instructions in
Appendix N: Changing the JVM Heap Size (p. 137).
4. There is a port conflict with the license server. This can occur if you are installing EKM R17 (or later) on a machine
where a pre-R17 License Manager is running. The license server uses Tomcat to provide the ANSYS License
Management Center. Prior to R17, Tomcat was configured to support the AJP protocol, which may conflict
with EKM R17.
Solution: Comment out the AJP connector in the License Manager’s Tomcat configuration file by
following these steps:
1. Edit the file C:\Program Files\ANSYS Inc\Shared Files\Licensing\tools\tom-

cat\conf\server.xml.
2. Search for “AJP 1.3".
3. Comment out the following line:

<Connector port="8009" protocol="AJP/1.3" redirectPort="8443" />
4. Restart the ANSYSLicensingTomcat service for the change to take effect.
Note
The ANSYSLicensingTomcat service must be restarted before the EKM server is

started.
5. There is another EKM cluster node with the same cluster name and cluster node name on the same LAN. Recall
from Naming the Cluster and Cluster Nodes (p. 27) that each EKM server on the same LAN must have a
unique cluster name, and that each cluster node within a cluster must have a unique node name.
If there is another EKM cluster node with the same cluster name and cluster node name on the
same LAN, EKM will fail to start, and will log an error message similar to the following:
2015-10-29 17:34:39,577 ERROR [org.jboss.as.clustering.jgroups.MuxChannel]
(MSC service thread 1-4) JGRP000016: exception in channelConnected()
callback: java.lang.IllegalStateException: JBAS010272: A node named node1:node1
already exists in this cluster. Perhaps there is already a server running
on this host? If so, restart this server with a unique node name,
via -Djboss.node.name=<node-name></node-name>
Solution: This issue can be resolved in either of the following ways:
Solution 1: Change the JGroups Multicast Configuration (p. 146) to configure the EKM server to use
a multicast configuration that does not conflict with other EKM server(s) on the same LAN.
Solution 2: Change the EKM cluster name to a unique name as described in Appendix S: Changing
the EKM Cluster Name (p. 147).
EKM Server is Slow or Unresponsive

EKM server has run out of memory.
Solution: Increase the JVM Heap Size for the EKM server (JBoss) by following the instructions in Appendix
N: Changing the JVM Heap Size (p. 137).
Unable to Connect to an EKM Server When Running in Service Mode

There is a firewall/port issue.
Workaround: Either disable the firewall on the machine where the EKM server is set up, or add the
EKM network port numbers to the firewall exception list. See Appendix B: Network Ports (p. 120) for a
list of network ports used by the EKM server.
The EKM Web Client Does Not Launch:“License framework initialization failed”
The license server is not running, or the EKM server is unable connect to it.
Solution: Restart the license server, then restart the EKM server.
EKM Web Client Window Suddenly Becomes Blank (Linux EKM Server)
The time on the Linux machine is behind the actual time.
Solution: Adjust the time on the Linux machine to the actual time.
Users Cannot Sign In, or Have Been Signed Out of EKM

1. A user account does not exist for a user who is trying to sign in. This can occur for the following reasons:
• If automatic account creation is enabled for the current workspace, the user is not entering the correct
username and/or password when signing in, and is therefore not being authenticated.
Solution: Ensure that the user has valid credentials for the active login module, and is entering
them correctly. For information about user authentication, see Configuring Login Authentica-
tion (p. 65).
• Automatic account creation is currently disabled for the current workspace, and an administrator has
not yet created a user account for the user.
Solution: Create a user account for the user. For details, see Adding and Modifying Users in the
Administration Guide.
To allow user accounts to be created automatically when users sign in to an EKM workspace, you
must set the createUsersAutomatically setting to true in the WorkspaceConfig.xml
file. See Configuration Settings in WorkspaceConfig.xml in the Administration Guide for details.
Otherwise, an administrator must create user accounts for users before they are able to sign in.
2. A user account exists for the user, but they are entering their credentials incorrectly. Consider the following:
• EKM requires that users enter their user name and password in a case-sensitive manner. Even if the user
is certain that they are entering the correct user name and password, they may be entering certain
characters using the wrong case.
Solution: Check to see if Caps Lock is enabled or Num Lock is disabled on the user’s keyboard.
Have the user type their user name and password in a text editor so that they can see what they
are typing.
Appendices
• The user’s password may have changed for the active login module. For example, if a user has changed
his/her OS password recently, but is entering an old password when signing in to EKM, he/she will not
be successfully authenticated to the OS if that is how users are authenticated in EKM.
Solution. Confirm the user’s current credentials for the active login module. For information about
user authentication, see Configuring Login Authentication (p. 65).
3. The EKM server has lost its connection to the license server. System administrators will receive an email when
this occurs. When an EKM server loses its connection to a license server, it will continue running for 60
minutes. After this period, if the connection has not been restored, the server will go into read-only mode.
Users will not be able to sign in to EKM, and signed-in users will be forcibly signed out.
Users who attempt to launch EKM when the license server is down, or when the EKM server is unable
to connect to it, will see the following exception: License framework initialization failed.
Solution: Ensure that the license server is available and running. For information about licensing
setup, see ANSYS Licensing (p. 18).
Note that if the EKM server is connected to the license server, but users cannot sign in, this indicates
that the maximum concurrent users are already signed in. For information about how licences are
used, see License Usage (p. 2).
4. Error: “missing response from all cluster nodes”. A node has gone down during workspace configuration, and
users cannot sign in after you have restarted the node.
Solution: Follow the steps below:
1. Stop the problematic EKM cluster node.
2. Sign in as the admin user that is configuring the workspace.
3. Revert the workspace changes.
4. Restart the problematic EKM cluster node.
5. Begin workspace configuration again.
6. Make the desired workspace changes, and then accept them.
Users Cannot Run Jobs

1. RSM has not been installed or properly configured, or the RSM Launcher service is not currently running.
Solution: Refer to Integrating EKM with Remote Solve Manager (RSM) in the Administration Guide.
2. The RSM Windows Domain has not been properly specified.
Solution: If the RSM Manager is running on Windows, edit the file EKM_HOME/conf/ekm.xml.
Set the value of the rsmWindowsDomain setting to the Windows domain name. Make sure that
you use the NetBIOS domain name and not the Fully Qualified Domain Name. For details refer to
the rsmWindowsDomain setting in the Specifying Remote Process Policies (<remoteProcess>)
section in the Administration Guide.
3. You have not properly specified the job data directory in the ekm.xml file, or specified directories that are visible
to compute nodes.
Solution: Ensure that the jobSourceRootPath and clusterVisibleDirectories settings

are correctly defined in the EKM_HOME/conf/ekm.xml file. For details refer to Specifying Remote
Process Policies (<remoteProcess>) (p. ?) in the Administration Guide.
4. Application definitions have not been added to job submission queues.
Solution: After the server has been started, go to Administration/Servers/Master, then select the
queue that you want to define. If the desired queue is not displayed, you will first need to synchronize
queues with those defined in RSM (see Synchronizing Job Submission Queues in the Administration
Guide).
For the selected queue, do one of the following:
• To automatically load the default applications defined in the EKM_HOME/conf/jobSubmissionAp-

plications folder, select Edit > Job Submission Settings and enable the Automatically load default
application definitions check box. Specify the operation system of the queue, then click OK.
• To create external applications, refer to Defining External Applications in the Administration Guide.
5. The wrong credentials are being used to submit a user’s jobs to RSM.
Solution: Refer to Specifying Job Management Preferences in the User’s Guide.
Log Messages
The logs contain repeated WARN log entries from JGroups, indicating discarded packets and different versions
of JGroups.
The JBoss logs and/or console output contain repeated WARN log entries from org.jgroups.pro-
tocols.UDP indicating JGroups is receiving and discarding packets from a sender using a different
version of JGroups. The log entries look like the following:
16:07:25,149 WARN [org.jgroups.protocols.UDP] (OOB-2,shared=udp-ekm)
JGRP000010: packet from 192.168.1.4:45689 has different version (3.2.7) than ours (3.4.5);
packet is discarded (received 29 identical messages from 192.168.1.4:45689 in the last 70002 ms)
These WARN log entries do not indicate a serious issue, but they make it more difficult to read the logs
and/or console output due to their frequency.
Solution: A host on the same LAN is running a process that uses an older version of JGroups, and this
process is sending packets using UDP multicast to the same multicast address and port as this EKM
cluster node is configured to use. The packets are not from the same version of JGroups, so this EKM
cluster node is discarding these packets and logging WARN log entries to alert you of the situation.
The process that is sending the packets is likely to be an EKM server or cluster node from an older
version of EKM, but it could also be another process not related to EKM.
Choose from the following solutions to resolve the issue:
Solution 1: The source of the packets is another EKM server which uses older version of EKM. Stop the
other EKM server to stop seeing these log messages.
Appendices
Solution 2: Change the JGroups Multicast Configuration (p. 146) of the EKM 17.0 server (or older EKM
server, if applicable) to configure the EKM server to use a multicast configuration that does not conflict
with other EKM server(s) on the same LAN.

ANSYS EKM Installation Guide PDF

Uploaded by

Document Information

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

ANSYS EKM Installation Guide PDF

Uploaded by

Copyright:

Available Formats

ANSYS EKM Installation Guide

ANSYS, Inc. Release 17.0

ANSYS, Inc. is certified to ISO 9001:2008.

U.S. Government Rights

Published in the U.S.A.

6.1.3. Set Up an X Server (Linux) ....................................................................................................... 38

9.3. Configuring EKM to Work with EnginFrame ..................................................................................... 84

14.4. Appendix D: Email Configuration ................................................................................................. 128

This guide contains the following chapters:

Cluster Database Server

Cluster File Server

EKM Server Account

Front-End Web Server

Multi-Node EKM Server

Single-Node EKM Server

2. EKM Path Variables

• EKM_BIN: Location of EKM supplemental binaries: EKM_HOME/bin.

• EKM_HOME: The EKM server application home directory: EKM_ROOT170/ekm-server.

• EKM_NODE_ROOT: The base directory for an EKM cluster node.

• EKM_TEMP: The directory that EKM uses for temporary files.

• JBOSS_HOME: The directory where the JBoss application server is installed.

• EKMDB_ROOT: The EKM database server (MySQL) base directory.

• MYSQL_HOME: The directory where the MySQL database server is installed.

• REPOSITORIES_HOME: The directory containing the EKM repositories: EKM_NODE_ROOT170/re-

3. Filesystem Path Conventions

1.1. Licensing and Access

Table 1.1: License Types/Access Levels

License Type/Access User Privileges User Restrictions

• Can add and modify content in both a

• Can launch jobs, processes and

Analyst • Can add and modify content in My • Cannot add/modify content in

• Can view and download content in

• Can launch jobs, processes and

Basic • Can view and download content in • Cannot add/modify content in

• Has no access to My Data, the Extrac-

• Cannot launch jobs, processes, or

1.2. License Usage

License Usage by Users

License Usage by Applications and Processes

License Usage Across Multiple Workspaces

License Fallback When Licenses are Unavailable

• Multi-user access (any number of users)

• LDAP/AD/Windows OS/Linux OS authentication

• Distributed file caching

• MySQL and Oracle database support

• Support for external databases

• Apache web-server integration

EKM servers are supported only on 64-bit operating systems.

2.1. Deployment Options

2.2. How an EKM Server is Configured

An EKM server configuration consists of the following components:

• One cluster file server (p. vii)

• One cluster database server (p. vii)

• One or more cluster nodes (p. vii)

• One front-end web server (p. viii)1.

2.3. Steps for Setting Up an EKM Server

Follow these steps to set up an EKM server:

1. Plan the EKM server deployment.

2. Review and fulfill the prerequisites.

3. Install the EKM server (p. 29).

4. Review the post-setup requirements (p. 37).

5. (Optional) Install a front-end web server (p. 43).

6. Set up login authentication and repository access (p. 65).