TEKSPEECH PRO
Device Operator Manager
Installation Guide
for Version 1.3.14
MN002092A03
Copyright
© 2017 ZIH Corp. and/or its affiliates. All rights reserved. ZEBRA and the stylized Zebra head are trademarks of
ZIH Corp., registered in many jurisdictions worldwide. All other trademarks are the property of their respective
owners.
COPYRIGHTS & TRADEMARKS: For complete copyright and trademark information, go to www.zebra.com/
copyright.
WARRANTY: For complete warranty information, go to www.zebra.com/warranty.
END USER LICENSE AGREEMENT: For complete EULA information, go to www.zebra.com/eula.
Terms of Use
• Proprietary Statement
This manual contains proprietary information of Zebra Technologies Corporation and its subsidiaries
(“Zebra Technologies”). It is intended solely for the information and use of parties operating and
maintaining the equipment described herein. Such proprietary information may not be used, reproduced,
or disclosed to any other parties for any other purpose without the express, written permission of Zebra
Technologies.
• Product Improvements
Continuous improvement of products is a policy of Zebra Technologies. All specifications and designs are
subject to change without notice.
• Liability Disclaimer
Zebra Technologies takes steps to ensure that its published Engineering specifications and manuals are
correct; however, errors do occur. Zebra Technologies reserves the right to correct any such errors and
disclaims liability resulting therefrom.
• Limitation of Liability
In no event shall Zebra Technologies or anyone else involved in the creation, production, or delivery of the
accompanying product (including hardware and software) be liable for any damages whatsoever
(including, without limitation, consequential damages including loss of business profits, business
interruption, or loss of business information) arising out of the use of, the results of use of, or inability to
use such product, even if Zebra Technologies has been advised of the possibility of such damages. Some
jurisdictions do not allow the exclusion or limitation of incidental or consequential damages, so the above
limitation or exclusion may not apply to you.
Revision History
Changes to the original guide are listed below:
Change Date Description
Rev A 07/16 Initial Release
-03 07/17 Updates to:
Instructions for handling HTTPS protocol.
Downloading and deploying DB Server specific java connector components.
Update versions and requirements.
2
Table of Contents
Copyright ........................................................................................................................................... 2
Terms of Use .................................................................................................................................... 2
Revision History ................................................................................................................................ 2
About This Guide
Introduction ....................................................................................................................................... 7
Notational Conventions ..................................................................................................................... 7
Icon Conventions .............................................................................................................................. 8
Related Documents and Software .................................................................................................... 8
Service Information ........................................................................................................................... 8
Provide Documentation Feedback .................................................................................................... 9
Introduction
Overview ......................................................................................................................................... 10
TekSpeech Pro DOM System Architecture ............................................................................... 10
Hardware Components ............................................................................................................. 11
Software Solution Stack ............................................................................................................ 11
Machine Size Recommendations .............................................................................................. 11
System Architecture Scenarios ................................................................................................. 12
Administrator Access ................................................................................................................ 13
System Architecture Scenarios ................................................................................................. 13
Single Instance Application Server with Local DB and Data ............................................... 13
Single Instance Application Server with Remote DB and NAS ........................................... 14
Multiple Application Server Instance ................................................................................... 15
Multiple Application Server and Web Server Instance ........................................................ 16
Configuration Topology ............................................................................................................. 17
File Storage Setup
Introduction to File Storage Setup .................................................................................................. 18
Remote File Share .................................................................................................................... 18
Migrating to a Remote File Share ............................................................................................. 18
Database Server Setup
Introduction to Database Server Setup ........................................................................................... 19
3
Table of Contents
Requirements ............................................................................................................................ 19
MySQL Database Server Configuration .................................................................................... 19
PostgreSQL Database Server Configuration ............................................................................ 20
Migration ................................................................................................................................... 20
Replication or Backup (optional) ............................................................................................... 20
Application Server Setup
Introduction to Application Server Setup ......................................................................................... 21
Requirements ............................................................................................................................ 21
Java Runtime Environment Install ............................................................................................. 21
Apache Tomcat Install ............................................................................................................... 22
Tomcat Log Configurations ................................................................................................. 22
Tomcat Connection Limits ................................................................................................... 24
Install Java JDBC Driver ........................................................................................................... 24
MySQL ................................................................................................................................ 24
PostgreSQL ......................................................................................................................... 24
Install the tsm and tsmapi Applications ..................................................................................... 24
Install Applications .............................................................................................................. 24
Configure User Data Location ............................................................................................. 24
Configure Database Connection ......................................................................................... 25
Start Tomcat Service and Log In ............................................................................................... 25
Enable tsm and tsmapi Log4j Logs ..................................................................................... 25
Configure Webservice Domain ................................................................................................. 26
Activate License ........................................................................................................................ 26
Firewall Setting .......................................................................................................................... 26
Clustering .................................................................................................................................. 26
Web Server Setup
Introduction to Web Server Setup ................................................................................................... 27
Activate IIS ................................................................................................................................ 27
Install Application Request Routing (ARR) ............................................................................... 27
Configure Server Farms ...................................................................................................... 27
Add Virtual Directory to File Storage ......................................................................................... 29
Configure URL Rewrite for HTTP .............................................................................................. 29
URL Redirect for tsm and tsmapi ........................................................................................ 29
URL Rewrite for Files .......................................................................................................... 30
Configure URL Rewrite for HTTPS ........................................................................................... 31
IIS Web Server Role and Features ..................................................................................... 31
Disable URL Rewrite Rules ................................................................................................. 31
URL Rewrite for Files .......................................................................................................... 31
Reverse Proxy URL Rewrite Rule ....................................................................................... 32
Edit Outbound Rule ReverseProxyOutboundRule1 .......................................
Edit Inbound Rule ReverseProxyInboundRule1 .................................................................. 32
Add MIME Types ....................................................................................................................... 33
Dashboard URL Reference ....................................................................................................... 33
Network Load Balancing Setup
Introduction to Network Load Balancing Setup ............................................................................... 34
..................... 32
4
Table of Contents
First Instance ............................................................................................................................. 34
Second or Later Instance .......................................................................................................... 34
DOM Upgrade
Introduction to DOM Upgrade ......................................................................................................... 36
Upgrade from V.1.3.12 .............................................................................................................. 36
Upgrade from V.1.3.6 ................................................................................................................ 36
Preserve the previous configurations .................................................................................. 36
Update tsm and tsmapi Application ..................................................................................... 37
Upgrade from Version earlier than V1.3.6 ................................................................................. 37
Tomcat Application Update ................................................................................................. 37
IIS Reconfiguration .............................................................................................................. 38
Data Backup and Restore
Introduction to Data Backup and Restore ....................................................................................... 39
Database Backup ...................................................................................................................... 39
MySQL Backup ................................................................................................................... 39
PostgreSQL Backup ............................................................................................................ 39
User Data Backup ..................................................................................................................... 40
Contain Symbolic Links ....................................................................................................... 40
No Symbolic Link ................................................................................................................ 40
Database Restore ..................................................................................................................... 40
MySQL Restore ................................................................................................................... 40
PostgreSQL Restore ........................................................................................................... 41
User Data Restore .................................................................................................................... 41
Restore from Zip ................................................................................................................. 41
Restore from VHD ............................................................................................................... 41
Rollback to Previous Version
Introduction to Rollback to Previous Version .................................................................................. 42
Install the Older Version ............................................................................................................ 42
Restore the Database and User Data Folder ............................................................................ 42
Setup Verification
Introduction to Verifying Your Setup ............................................................................................... 43
Troubleshooting ........................................................................................................................ 43
“Connection Error" or Deployment Failure .......................................................................... 43
Unable to Login - Keeps Showing Me the Logon Page ...................................................... 43
500 level Error ..................................................................................................................... 43
Not Responding or Page Not Found after Clicking on the Account icon at Admin Page .... 43
Version Information
TekSpeech Pro DOM Version Information ...................................................................................... 44
Version 1.3.14 ........................................................................................................................... 44
Version 1.3.12 ........................................................................................................................... 44
Version 1.3.6
............................................................................................................................. 44
5
Table of Contents
Version 1.3.2 ............................................................................................................................. 45
Version 1.2.7 ............................................................................................................................. 45
Version 1.2.6 ............................................................................................................................. 45
6
About This Guide
Introduction
This installation guide describes how to install TekSpeech Pro Device and Operator Manager (DOM).
Topics covered in this guide are as follows:
• Introduction
• File Storage Setup
• Database Server Setup
• Application Server Setup
• Web Server Setup
• Network Load Balancing Setup
• DOM Upgrade
• Data Backup and Restore
• Rollback to Previous Version
• Setup Verification
• Version Information
Notational Conventions
The following conventions are used in this document:
• Bold text is used to highlight the following:
• Dialog box, window and screen names
• Drop-down list and list box names
• Check box and radio button names
• Icons on a screen
• Key names on a keypad
• Button names on a screen.
7
• Bullets (•) indicate:
• Action items
• Lists of alternatives
• Lists of required steps that are not necessarily sequential.
• Sequential lists (e.g., those that describe step-by-step procedures) appear as numbered lists.
Icon Conventions
The documentation set is designed to give the reader more visual clues. The following graphic icons are used
throughout the documentation set. These icons and their associated meanings are described below.
WARNING! The word WARNING with the associated safety icon implies information that, if disregarded,
could result in death or serious injury, or serious product damage.
CAUTION The word CAUTION with the associated safety icon implies information that, if disregarded, may result
in minor or moderate injury, or serious product damage.
About This Guide
IMPORTANT text text text text text text text text text text text text text text text text text text text text text text
text text text text text text text text text text text text text text text text text text text text text text
text text text text text text text text text text text text text text text text text text text text text text
text text text text text text text text text
NOTE NOTE contains information more important than the surrounding text, such as exceptions or
preconditions. They also refer the reader elsewhere for additional information, remind the reader how to
complete an action (when it is not part of the current procedure, for instance), or tell the reader where
something is located on the screen. There is no warning level associated with a note.
Related Documents and Software
For the latest version of this guide and all related documentation, go to: zebra.com/support.
Service Information
If you have a problem with your equipment, contact Zebra Global Customer Support for your region. Contact
information is available at: zebra.com/support
When contacting support, please have the following information available:
• Serial number of the unit
.
• Model number or product name
• Software type and version number.
Zebra responds to calls by email, telephone or fax within the time limits set forth in support agreements.
If your problem cannot be solved by Zebra Customer Support, you may need to return your equipment for servicing
and will be given specific directions. Zebra is not responsible for any damages incurred during shipment if the
approved shipping container is not used. Shipping the units improperly can possibly void the warranty.
8
About This Guide
If you purchased your Zebra business product from a Zebra business partner, contact that business partner for
support.
Provide Documentation Feedback
If you have comments, questions, or suggestions about this guide, send an email to EVM-Techdocs@zebra.com.
9
Introduction
Overview
TekSpeech Pro Device and Operator Manager (DOM) consists of four main components:
• Web server
• Application server
• Database server
• Data server.
This guide is presented in order of installation steps. All of the servers can be installed on one machine (see Single
Instance Application Server with Local DB and Data on page 13), be installed as clusters (see Multiple Application
Server Instance on page 15), or installed on multiple machines (see Multiple Application Server and Web Server
Instance on page 16). This guide also presents one example of load balancing in the clustered setup.
For an understanding of the solution stack, see Software Solution Stack on page 11.
TekSpeech Pro DOM System Architecture
Figure 1 TekSpeech Pro DOM in Relation to Other Components in the Complete System
10
Introduction
Hardware Components
Table 1 Hardware Components
Component Description/Purpose
Database
Server
Application
Server
Web Server Provide the web frontend to the Application Server. Includes browser access for administrators
Data Storage Provide unstructured data access to the application. Includes PDK files, firmware files, operator
Provide structured data access to the application.
Provide the execution of the TekSpeech Pro DOM application.
and web service access for device clients.
profiles, configurations, and extra resources. This can be provided locally on the same machine
as the Application server or provided remotely (For example, using NAS technology).
Software Solution Stack
Table 2 Required Software components
Stack
Component
Operating
System
Windows Server 2008 R2, 64-bit or
Windows Server 2012, 64-bit or
Windows Server 2012 R2, 64-bit or
Windows Server 2016, 64-bit
Version
Database
Server
Java Runtime Java SE Runtime Environment 8uXX, 64-bit (version 1.8.0_131-b11 verified)
Java Server Apache Tomcat 7.0.xx, 64-bit (version 7.0.78 verified)
Application TekSpeech Pro Device and Operator Manager (DOM)
Web Server Microsoft IIS (as included with Operating System)
MySQL Server, 64-bit (5.6 or 5.7) or
PostgreSQL, 64-bit (9.4.x or 9.6.x) and supporting Java DB connector library
Machine Size Recommendations
Table 3 Recommended Hardware (or virtual) Resource Requirements
Server Cores RAM Disk Storage
Application Server
Small (< 100 operators) 2 4 GB 5 GB
Medium (100 - 500 operators) 4 8 GB 20 GB
11
Introduction
Table 3 Recommended Hardware (or virtual) Resource Requirements (Continued)
Server Cores RAM Disk Storage
Large (> 500 operators) 8 16 GB 50 GB
Database Server
Small (< 100 operators) 2 2 GB 5 GB*
Medium (100 - 500 operators) 4 4 GB 20 GB*
Large (> 500 operators) 8 8 GB 50 GB*
* Database Size: 1 GB + 10 MB per device
Network Storage Server 5 GB + 60 MB per
operator
System Architecture Scenarios
Consider the information in the following table when planning a TekSpeech Pro DOM system installation. The
information provided should help determine the correct architecture based on an organization's goals for size,
performance and reliability.
.
Table 4 System Architecture Scenarios
Scenario Features
Single Instance Application Server
• Single local application server instance
• Single local web server instance
• Single local (or remote) database server
• Single local (or remote) data storage (NAS)
• Intended for small systems with less than 250
operators.
• The web server, application server, database
server, and storage could be provided on the
same machine.
• The database and/or data storage could be
provided on separate machines for improved
performance and reliability.
Multiple Instance Application Servers
• Multiple application server instances.
• Single or multiple, local or remote web server
instances.
• Remote database server
• Remote data storage (NAS)
• Provides for best performance.
• Provides for best redundancy and availability.
• Load balancing and application server affinity is
provided by the web server.
• Further redundancy can be provided with a
frontend load balancing technology.
12
Administrator Access
Table 5 Administrator Access
Introduction
Browser
Parameter
Target Screen
Resolution
Name and
Version
1280 x 1024 pixels
Google Chrome 34
Safari 7
Firefox 27
Internet Explorer 10
Minimum Requirement
System Architecture Scenarios
Single Instance Application Server with Local DB and Data
In this scenario, all of the software stack components are installed on one machine. This scenario should only be
used for small systems.
Figure 2 Single Instance Application Server with Local DB and Data
13
Introduction
Single Instance Application Server with Remote DB and NAS
In this scenario, the web server and application server are installed on one machine. The database server and
NAS are installed on separate machines. This scenario can be used in small to medium sized systems where
performance is important but redundancy is not important.
Figure 3 Single Instance Application Server with Remote DB and NAS
14
Introduction
Multiple Application Server Instance
In this scenario, there are multiple instances of the application server, a single instance of the web server, and
remote database and NAS servers. This provides improved performance and allows for some redundancy.
Figure 4 Multiple Application Server Instance
15
Introduction
Multiple Application Server and Web Server Instance
In this scenario, there is a web server and application server per machine. A frontend network load balancer
redirects traffic to one of the web servers. This provides improved performance and allows for maximum
redundancy.
Figure 5 Multiple Application Server and Web Server Instance
16
Introduction
Configuration Topology
The configuration topology diagram below shows an overview of the hierarchy of configuration items in the Device
And Operator Manager (DOM). The DOM define sites, applications, devices, and operators that are used to
administer a TekSpeech Pro solution.
Figure 6 Configuration Topology
17
File Storage Setup
Introduction to File Storage Setup
TekSpeech Pro DOM requires user data storage for the PDK files, firmware files, operator profile, configurations,
extra resources, and so on. For information about disk size requirements, see Machine Size Recommendations on
page 11
If you want to use the local folder as storage or are performing an upgrade, you may skip this section.
Remote File Share
To provide a remote file share:
1. Create a new shared directory.
2. Change the folder permissions and shared users so that a particular user or group of domain-level users can
have full access (create, write, read) to the directory from the web server.
It cannot be a local user because it needs to be accessible from other machines in the same domain.
Migrating to a Remote File Share
To migrate to a remote file share:
1. If you are migrating from a local storage location to a remote file share, copy the entire content of your user
data to your remote file share.
Default location of user data:
CAUTION: If you have symbolic links in the folder (you most likely will if you migrated from TekSpeech Pro DOM
version 1.2.X), use robocopy or xcopy with the appropriate flag (robocopy /sl or xcopy /b). You will also need to
verify the symbolic links are still valid after the move. Symbolic links are not used in TekSpeech Pro DOM version
1.3.x and later.
c:\tekspeechmanager-data
18
Database Server Setup
Introduction to Database Server Setup
The supported database server types are MySQL and PostgreSQL. The installation of the databases is not
covered in this guide, but the configuration after installation is. TekSpeech Pro DOM needs two databases: one for
static data and another for dynamic user data.
When performing an upgrade using an existing database, you may skip this section.
Requirements
The database server must be configured to allow up to 120 concurrent connections for each TekSpeech Pro DOM
application server to provide connection polling. If you have two application servers, allow a minimum of 240
connections. For information about disk size requirements, see Machine Size Recommendations on page 11
MySQL Database Server Configuration
For MySQL setup, you will need to manually create one database for the static data. The second database will be
created by TekSpeech Pro DOM automatically after activation.
To create the databases on the server:
1. For a MySQL database server, the following commands are (minimally) required to create the databases on
the server:
mysql> CREATE DATABASE tsm DEFAULT CHARACTER SET utf8;
2. Edit the my.ini file (usually found in %PROGRAMDATA%\MySQL\MySQL Server 5.6) to set the max_connections to
120 (or larger if desired) per application server.
3. Restart the database.
To allow remote access to the server:
1. For a MySQL database server, the following commands are (minimally) required to allow remote access to the
server for user
this step. If you have created another user other than root for remote access by TekSpeech Pro DOM,
substitute that user and <password> for the
mysql> GRANT ALL PRIVILEGES ON *.* TO
mysql> FLUSH PRIVILEGES;
Where
the user that will connect to the database.
<user> is the user that will connect to the database (default root) and <password> is the password of
root. If you are installing the database on the same host as the application, then you may skip
root user.
'<user>'@'%' IDENTIFIED BY '<password>';
19
Database Server Setup
PostgreSQL Database Server Configuration
For PostgreSQL setup, you will need to create two databases manually, unlike the MySQL setup.
To create the databases on the server:
1. For PostgreSQL database server, the following commands are (minimally) required to create the databases on
the server:
CREATE DATABASE tsm WITH OWNER "postgres" ENCODING 'UTF8'
CREATE DATABASE tsmaccount WITH OWNER "postgres" ENCODING 'UTF8'
1. Edit the postgresql.conf file (usually found in the data subdirectory of the \PostgreSQL\<version> installation
directory) to set the max_connections to 120 (or larger if desired) per application server.
2. Save the file.
3. Edit the pg_hba.conf file (usually found in the data subdirectory of the \PostgreSQL\<version> installation
directory to add the following lines using the appropriate subnetwork at your site.
If your sub-network is "B-class", then provide 2 octets from your sub-network and use the trailing /16 to indicate
that the first 16-bits of your sub-network is fixed and the remaining 16-bits are variable. If your sub-network is
"C-class", then provide 3 octets from your sub-network and use the trailing /32 to indicate that the first 32-bits
of your sub-network is fixed and the remaining 8-bits are variable.
The following is an example for a sub-network of 10.72.x.x for a "B-class" sub-network:
# TYPE DATABASE USER ADDRESS METHOD
# Remote connections on same sub-network.
host all all 10.72.0.0/16 md5
1. Restart the database.
Migration
You can migrate from one database to another if they are of the same type (For example, from MySQL to MySQL).
To migrate from one database to another:
1. Stop all your applications (For example, Tomcat services).
2. Perform a full backup from the existing database.
3. Recreate/restore the database and schema on the new server.
NOTE: For MySQL, you may need to disable foreign_key_checks before you restore the database and enable
foreign_key_checks after the restore.
Replication or Backup (optional)
You may enable database replication or schedule a backup in case of failure.
20
Application Server Setup
Introduction to Application Server Setup
Requirements
• Java SE Runtime Environment version 8uXX, 64-bit.
• Apache Tomcat version 7.0.xx, 64 bit.
• TekSpeech Pro DOM Application (tsm.war and tsmapi.war).
• Dom-config.properties template files
• Access to the following server:
• License server: https://ls-msi.mcl4e.com or 54.195.246.173 port 443
• Reference Data Server: http://refdb-msi.mcl4e.com or 54.195.246.173 port 80
For information about the machine size recommendation for the host’s RAM and disk size requirement, see
Machine Size Recommendations on page 11
Java Runtime Environment Install
To install Java Runtime:
1. Download the latest version 8uXX installer from Oracle.
2. Follow the installer to complete the setup.
3. Add a System Environment variable JRE_HOME that contains the installation folder name.
Example:
C:\Program Files\Java\jre1.8.0_77
WARNING: If an update of JRE is installed later, this variable needs to be updated accordingly.
21
Application Server Setup
Apache Tomcat Install
To install Tomcat:
1. Download the Apache Tomcat version specified. For convenience, you may choose the installer version of
Apache Tomcat. When running the installation wizard, ensure to choose the option to run Apache Tomcat as a
service. At the end of the installation, Apache Tomcat should be installed into the following directory:
C:\Program Files\Apache Software Foundation\Tomcat 7.0.
2. If you choose the Windows zip file instead of the installer, for example,
apache-tomcat-7.0.68-windows-x64.zip, perform the following procedure:
a. Create the directory: C:\Program Files\Apache Software Foundation.
b. Unzip the contents to C:\Program Files\Apache Software Foundation.
c. Rename the folder from the extracted name to "Tomcat 7.0". For example,
> rn "apache-tomcat-7.0.68" "Tomcat 7.0"
d. Add the System Environment variable "CATALINA_HOME" to be the root of the Tomcat folder. For
Example:
e. Open the command prompt as administrator and navigate to %CATALINA_HOME%\bin and execute the
command service.bat install.
C:\Program Files\Apache Software Foundation\Tomcat 7.0.
3. If not already performed in step 2.d., above, ensure to add the System Environment variable "CATALINA_HOME"
to be the root of the Tomcat folder. For example,
7.0
.
4. Open the command prompt as administrator and navigate to %CATALINA_HOME%\bin and execute the command
"tomcat7w.exe" and wait for the Tomcat properties window to open.
a. Set startup type to automatic in the General tab.
b. Set the following fields under the Java tab:
i. Initial memory pool = 256 MB
ii. Maximum memory pool = 1024 MB
c. Add the following in the Java options (including the dash (-)) under the Java tab:
i. -XX:MaxPermSize=256m
ii. -Dfile.encoding=UTF8
WARNING: If an update of JRE is installed later, then the Java Virtual Machine path under the Java tab
needs to be updated accordingly to that specific version.
5. This step is only required if you encounter "Application System Error Access is denied. Unable to open the
C:\Program Files\Apache Software Foundation\Tomcat
service 'Tomcat7'" during service startup.
a. Navigate to %CATALINA_HOME%\bin in Explorer and right-click tomcat7w.exe.
b. Select properties and go to the Compatibility tab.
c. Select Run this program as an administrator under privilege level.
d. Click OK.
Tomcat Log Configurations
By default, Tomcat logs keep growing as you use it. You want to set up log rotation or schedule archiving/deleting
of the log files to avoid filling up the disk. The logs are stored in
%CATALINA_HOME%\logs. To understand Tomcat
22
Application Server Setup
logging, see http://tomcat.apache.org/tomcat-7.0-doc/logging.html. The following sections are examples of what
you can configure for the logs.
Turn off Tomcat STDOUT and STDERR Logs
In most cases, stdout and stderr logs contain the information from all the applications you enabled under webapps.
You can enable logging for the applications of interest (For example, tsm and tsmapi).
To disable stdout and stderr logging:
1. Open the Tomcat Java properties (by running Tomcat7w)
2. Clear the fields for Redirect stdout and redirect stderror in the Logging tab.
3. Save and restart Tomcat.
Turn off Localhost Access Logs
It is recommended to turn the localhost connection log off in the production environment as the number of
transactions will cause the disk to fill up really quickly and may impact performance.
To turn the logging off:
1. Open %CATALINA_HOME%\conf\server.xml and comment the following property out:
<Valve className="org.apache.catalina.valves.AccessLogValve" directory="logs"
prefix="localhost_access_log." suffix=".txt"
pattern="%h %l %u %t "%r" %s %b" />
2. Restart Tomcat.
Turn off or Log Rotate Miscellanies Logs
Standard Tomcat installation uses java.utils.logging (JULI) and produces catalina, localhost, manager, and
host-manager log files. These files most likely are small files but they will eventually add up. You can safely disable
these logs for the purpose of TekSpeech Pro DOM.
To disable these log files:
1. Remove %CATALINA_HOME%\conf\logging.properties and restart Tomcat.
It will not create more logs but you will need to purge the old logs manually.
2. If you would still like to keep the logs but keep them under a size limit, you have to configure Tomcat to use
log4j instead of JULI.
Instructions to convert to log4j can be found at
http://tomcat.apache.org/tomcat-7.0-doc/logging.html#Using_Log4j
3. Instead of using DailyRollingFileAppender, you want RollingFileAppender to control the size and the
.
number of backup files.
Class reference can be found at
http://logging.apache.org/log4j/1.2/apidocs/org/apache/log4j/RollingFileAppender.html
.
Nightly Schedule Task
You may create a batch file that monitors the log folder to compress logs and purge the ones that are over a certain
age. If you do not have this mechanism and do not have the log rotation setup, your disk will eventually fill up.
23
Application Server Setup
Tomcat Connection Limits
This guide uses the Tomcat's HTTP Connector to server as a stand-alone server. Depending on the number of
devices you have, you may need to adjust the maxThreads and maxConnections setting by modifying the
%CATALINA_HOME%\conf\server.xml file.
Example:
<Connector port="8080" protocol="HTTP/1.1"
connectionTimeout="20000"
redirectPort="8443"
maxConnections="-1"
maxThreads="500" />
For descriptions of the two attributes and additional attributes, see
http://tomcat.apache.org/tomcat-7.0-doc/config/http.html
.
Install Java JDBC Driver
MySQL
To install the MySQL Java Database Connector (JDBC) driver:
1. Download the Java Database Connector from http://dev.mysql.com/downloads/connector/j/.
Select the driver that matches your versions of MySQL database and Java runtime.
2. Extract the contents of the compressed file and locate the .jar library file.
3. Copy the .jar file to %CATALINA_HOME%\lib.
PostgreSQL
To install the PostgreSQL Java Database Connector (JDBC) driver:
1. Download the Java Database Connector from http://jdbc.postgresql.org/download.html.
Select the driver that matches your version of PostgreSQL database and Java runtime.
2. Extract the contents of the compressed file and locate the .jar library file.
3. Copy the .jar file to %CATALINA_HOME%\lib.
Install the tsm and tsmapi Applications
Install Applications
To install the applications:
1. Ensure the Apache Tomcat service is stopped.
2. Copy tsm.war and tsmapi.war to %CATALINA_HOME%\webapps.
Configure User Data Location
To configure the user data location:
1. Choose the correct dom-config.properties file from the template and copy to %CATALINA_HOME%\conf. Make
sure the file name is renamed to dom-config.properties.
2. Open dom-config.properties in %CATALINA_HOME%\conf.
24
Application Server Setup
3. Enter the path of the data folder on the right hand side of “filerepository.shared.root.directory=”.
Example:
4. Save the file when finished.
filerepository.shared.root.directory=c:/tekspeechmanager-data/
NOTE: For this path, ensure to use “forward slash” characters (/) and not “back slash” characters (\).
If you use remote file server, please open command prompt as administrator to c:\ and enter the following
commands:
1. mklink /D tekspeechmanager-data \\<fileshareserver>\<sharedfoldername>
Example: mklink /D tekspeechmanager-data \\10.72.1.7\DOM-data
2. fsutil behavior set SymlinkEvaluation R2R:1 R2L:1
As the Tomcat service is going to access this link, you will need to configure the “Log on” tab for Tomcat. Steps are
described in Start Tomcat Service and Login section.
Configure Database Connection
To configure the database connection:
1. Edit dom-config.properties in %CATALINA_HOME%\conf
a. Replace the properties with square brackets with your specific setup.
[SERVER_IP]
[SERVER_PORT]
[DB_USERNAME]
[DB_PASSWORD]
Default port for MySQL is 3306 and PostgreSQL is 5432. Please ensure the username of password you
provided here has the privileges to create new schema and tables in the database.
Start Tomcat Service and Log In
To start the Tomcat Service and log in:
1. Open the services application in the control panel.
2. If you are using remote file storage location, go to the Log on tab and specify a user with read/write permission
to the file location.
3. Start the Tomcat service. It may take a few minutes before the application is ready.
4. Open a web browser to http://localhost:8080/tsm/admin/login.html. You should be able to see the login page
once it is loaded.
5. Log in using the credentials "admin/admin”.
Enable tsm and tsmapi Log4j Logs
If you have disabled stdout and stderr logging in the previous section, you may want to enable logging for tsm and
tsmapi. Open tsm\WEB-INF\classes\log4j.properties and tsmapi\WEB-INF\classes\log4j.properties. The following
shows a sample configuration for the tsm application's properties file:
#log4j.rootLogger=INFO, stdout
log4j.rootLogger=INFO, stdout, logfile
log4j.appender.logfile=org.apache.log4j.RollingFileAppender
25
Application Server Setup
log4j.appender.logfile.File=${catalina.base}/logs/tsm.log
log4j.appender.logfile.MaxFileSize=100MB
# Keep five backup files.
log4j.appender.logfile.MaxBackupIndex=5
# Pattern to output: date priority [category] - message
log4j.appender.logfile.layout=org.apache.log4j.PatternLayout
log4j.appender.logfile.layout.ConversionPattern=%d %p [%c] - %m%n
There are some lines that begin with
example above for tsm app configures logging so that each file will be a maximum of 100 MB and up to five
previous files will be kept (with one active file written by Tomcat). If you do not have catalina.base variable set in
your java options, then you can replace it with the absolute path.
For information on RollingFileAppender, see
http://logging.apache.org/log4j/1.2/apidocs/org/apache/log4j/RollingFileAppender.html
For information on how to change the format of the lines in the log files, see
http://logging.apache.org/log4j/1.2/apidocs/org/apache/log4j/PatternLayout.html
Restart Tomcat after changes are completed.
log4j.appender.stdout and log4j.logger that can be kept as they are. The
.
.
Configure Webservice Domain
The Webservice Domain in the Properties of Administration Dashboard needs to point to the web server's domain.
It is used when generating the configuration file (For example, loader.ini) for the devices so that they can connect
to this server. The Webservice Domain is the hostname or IP address of this server or the hostname or IP address
of the eventual load balancing server. If your web server is behind a load balancer, set this value to hostname or IP
address of the load balancer. Restart Tomcat services (on all application servers) once you saved the change. Its
pattern is as follows: <hostOrIpAddress>/tsmapi.
Activate License
If this is a first-time installation (i.e., not an upgrade), you will need to activate the TekSpeech Pro DOM at this time
before configuring the web server. Register the license first (link from the license email) before clicking on the
Activation icon on the Administration Dashboard.
Firewall Setting
If you are going to install the web server on another host, allow access to the Tomcat port (For example, port
8080). Add a rule in the firewall to allow port 8080 to be accessed. Skip this section if you are using the single
instance installation.
Clustering
For clustered setup, repeat this entire section to set up the second server. The load balancing is handled by the
web server in
Web Server Setup.
26
Web Server Setup
Introduction to Web Server Setup
This chapter provides instructions to install the web server on a Windows server using IIS and ARR. If you use
another method of balancing other than ARR, remember to enable sticky session. Note that in this guide, the
"Default web site" is used for configuration. If you would like to reserve this site for another purpose, you may
create a new site for TekSpeech Pro DOM.
NOTE: JK ISAPI redirector with IIS is not supported by Apache on Windows 2008 and later. There are some
issues with using it for a clustered application server setup. JK ISAPI redirector may work for a single instance but
it is not the supported configuration going forward. ARR is better supported from Microsoft and is directly
integrated with IIS.
Activate IIS
If IIS is not enabled in the server manager, enable it in this step.
Install Application Request Routing (ARR)
Access the Microsoft support site and download the latest ARR for your IIS version. IIS 7.5 uses ARR v3. The
simplest method to install ARR is by using the Web Platform Installer (Web PI) at
www.microsoft.com/web/downloads/platform.aspx
following the instructions:
http://blogs.technet.com/b/erezs_iis_blog/archive/2013/11/27/installing-arr-manually-without-webpi.aspx
Once it is installed, launch IIS Manager and you should see a new node "Server Farms" under the server name.
Configure Server Farms
Prior to configuring the server farms in this section, you should know the host names and ports for your application
servers. Your web server needs to be able to access
http(s)://[host ip address]:[port]/tsm/admin/login.html before attempting the following steps. If you are
performing a single instance installation, then you only need to enter one host.
Create Server Farm
To create a server farm:
1. Launch IIS manager and expand your server node.
2. Right-click Server Farms and click Create Server Farm.
3. Enter the farm name Tomcat, verify Online is checked, and click Next.
. If you would like to install manually, Microsoft suggests
27
Web Server Setup
4. In this step, you will need to provide the application server details:
a. Enter the Server address (For example, 127.0.0.1 for the local system).
b. Click the Advanced Settings link, and enter the httpPort value under the applicationRequestRouting
node. Default for Tomcat is 8080.
c. Click Add and continue to add all of the application servers.
5. Click Finish.
Enable Routing Rules
To enable routing rules:
1. Click Tomcat server farm, and then open Routing Rules.
2. Check Use URL Rewrite to inspect incoming requests.
3. Click Apply in the Actions pane.
Use Server Affinity
Enable this feature to preserve sticky sessions. It is optional for a single instance setup but is still recommended to
configure this.
To use server affinity:
1. Click Tomcat server farm.
2. Click Server Affinity in the feature view.
3. Check the Client Affinity option to enable Client Affinity.
4. Ensure the default value of ARRAffinity is used as the value for the Cookie name field.
5. Click Apply.
NOTE: In order for client affinity to work as expected, you need a browser with cookies enabled. Also, your host
name in the URL is required to contain a "." (dot) for your browsers to correctly return the cookie. For example, a
host name that does not comply: http://localhost/tsm/admin/login.html will not correctly return cookies to the
server. However, if you change the URL address to
cookies will be returned correctly.
http://127.0.0.1/tsm/admin/login.html, then
Configure Health Test
The URL Test feature allows ARR to mark servers as unhealthy if it fails the check and mark them as healthy once
it passes the check at a later time.
To configure the health test:
1. Click Tomcat server farm.
2. Click Health Test in the feature view.
3. Enter http://localhost/tsm/notfounddispatcher.html in the URL field under URL Test.
4. Click Apply in the Actions pane.
You can verify the URL test after you have configured the URL Redirect in the next section.
CAUTION: It is advised that you come back to verify the URL test after you configured the URL redirect. If you
make a mistake, ARR will mark your servers as unhealthy and they will be inaccessible.
28
Web Server Setup
Add Virtual Directory to File Storage
This virtual directory points the path to user data for TekSpeech Pro DOM. The web server needs to have at least
read access to the file share.
To add virtual directory to file storage:
1. Verify that you have a folder named with your account number in your user data directory (For example,
c:\tekspeechmanager-data\files\4313190257 if your user data directory is set to the default.) If this folder
does not exist, create it. You can find out your account number by going to
http://localhost:8080/tsm/admin/home.html
immediately after "
http://localhost:8080/tsm/4313190257/admin/home.html.)
2. In IIS manager, right-click Default Web Site (or the site you are using for this application) and choose Add
Virtual Directory.
3. Fill in the alias = files and choose the physical path to be the file share host, pointing to the license number.
Example:
c:\tekspeechmanager-data\files\4313190257 for a local folder.
4. Click Connect as and fill in the credentials that have the permissions to the folder. (skip this for a local folder).
5. Click OK.
\\10.72.1.7\DOM-data\files\4313190257 for a remote share or
tsm/" and before "/admin" (For example,
and click Account. Your account number is in the URL
Configure URL Rewrite for HTTP
Configuring URL Rewrite rules differ depending on whether you intend to expose the application via HTTP
(unencrypted via port 80) or HTTPS (encrypted via port 443) protocol. Only configure the URL Rewrite rule for your
intended protocol. It is recommended to use the HTTP protocol for better performance.
In this section, use IIS to redirect the tsm and tsmapi requests to the Tomcat Application server. Instead of passing
the get requests (during deployment for example), create a rule to get the file directly.
For the following two sections, click on the server name in the connection pane in IIS and open URL Rewrite.
NOTE: URL Rewrite rules should be created at the server (top) level.
URL Redirect for tsm and tsmapi
To configure the URL redirect for tsm and tsmapi:
1. In the URL Rewrite feature, highlight the ARR_Tomcat_loadbalance rule and then click Edit from the
Inbound Rules section of the Actions list.
2. Enter the following:
Table 6 URL Redirect for tsm and tsmapi
Field Enter the following:
Name ARR_Tomcat_loadbalance
Match URL:
Requested URL Matches the Pattern
Using Regular Expressions
29
Web Server Setup
Table 6 URL Redirect for tsm and tsmapi
Field Enter the following:
Pattern ^((tsm)|(tsmapi))/.*$
Ignore case Checked
Condition None
Server variables None
Action
Action type Route to Server Farm
Scheme http
Server farm Tomcat
Path /{R:0}
Stop processing of
subsequent rules
Checked
URL Rewrite for Files
To configure the URL rewrite for files:
1. In the URL Rewrite feature, click Add Rules from the Actions list.
2. Under the Inbound rules section, select the blank rules template and click OK.
3. Enter the following:
Table 7 URL Rewrite for Files
Field Enter the following:
Name Rewrite rule for files
Match URL:
Requested URL Matches the Pattern
Using Regular Expressions
Pattern ^tsmapi/file/(files/.*)$
Ignore case Checked
Condition None
Server variables None
Action:
Action type Rewrite
Rewrite URL {R:1}
Append query string Unchecked
Stop processing of
subsequent rules
Checked
30
Web Server Setup
4. Click Apply.
5. Click Back to Rules.
6. Highlight this rule and move it to the top.
Configure URL Rewrite for HTTPS
Configuring URL Rewrite rules differ depending on whether you intend to expose the application via HTTP
(unencrypted via port 80) or HTTPS (encrypted via port 443) protocol. Only configure the URL Rewrite rule for your
intended protocol.
IIS Web Server Role and Features
Ensure to disable all Performance (Web Server (IIS)/Web Server/Performance) features for compression. That is,
disable Static Content Compression and Dynamic Content Compression.
Disable URL Rewrite Rules
If you previously configured the IIS server with URL Rewrite Rules, ensure to disable any URL Rewrite Rules at the
Server (parent) level that might conflict with these rules outlined below.
URL Rewrite for Files
To configure the URL rewrite for files:
1. In the URL Rewrite feature (at the "Default Web Site"), click Add Rules from the Actions list.
2. Under the Inbound rules section, select the blank rules template and click OK.
3. Enter the following:
Table 8 URL Rewrite for Files
Field Enter the following:
Name Rewrite rule for files
Match URL:
Requested URL Matches the Pattern
Using Regular Expressions
Pattern ^tsmapi/file/(files/.*)$
Ignore case Checked
Condition None
Server variables None
Action:
Action type Rewrite
Rewrite URL {R:1}
Append query string Unchecked
Stop processing of
subsequent rules
Checked
31
Web Server Setup
4. Click Apply.
5. Highlight this rule and move it to the top.
Reverse Proxy URL Rewrite Rule
1. In the URL Rewrite feature (at the "Default Web Site"), click Add Rules from the Actions list.
2. Under the Inbound and Outbound Rules section, select the Reverse Proxy template and click OK.
3. Enter the following:
Table 9 Reverse Proxy URL Rewrite Rule
Field Enter the following:
Inbound Rules/ Enter the
localhost:8080
server name …
Enable SSL Offloading Checked
Outbound Rules/ Rewrite the
Checked
domain names …
From:
localhost:8080
To: <domain name of ARR server>
Example:
4. Click OK.
dom.mycompany.net
Edit Outbound Rule ReverseProxyOutboundRule1
1. In the URL Rewrite feature, double-click the ReverseProxyOutboundRule1 in the Outbound rules … area.
2. Click the Edit button next to the Precondition.
3. Add a new precondition:
Table 10 Reverse Proxy URL Rewrite Rule
Field Enter the following:
Condition Input
Check if input string
Pattern
Ignore case
4. Click Apply.
{REQUEST_URI}
Matches the Pattern
.*tsm.*
Checked
Edit Inbound Rule ReverseProxyInboundRule1
1. In the URL Rewrite feature, double-click the ReverseProxyInboundRule1 in the Inbound rules … area.
2. Update the following:
32
Web Server Setup
Table 11 Reverse Proxy URL Rewrite Rule
Field Enter the following:
Match URL / Pattern:
3. Click Apply.
Add MIME Types
To add MIME types:
1. In IIS, click the server name.
2. Open MIME Types in the feature pane.
3. Add the following:
Table 12 MIME Types
File name
extension
.apk text/plain
.pdc text/plain
.pdk text/plain
.mvt text/plain
.mtp text/plain
(^((tsm)|(tsmapi))/.*$)
MIME Type
.lmd text/plain
.dat text/plain
Dashboard URL Reference
Now that the web server is set up, use the following URL reference to access common targets.
Table 13 URL Reference
Purpose URL
Administration
Dashboard
Account http(s)://<host>/tsm/<account id>/admin/home.html
Site http(s)://<host>/tsm/<account id>/<site name>/home.html
http(s)://<host>/tsm/admin/home.html
33
Network Load Balancing Setup
Introduction to Network Load Balancing Setup
This chapter provides an example on how to set up a clustered web server using the network load balancing
feature from Windows server. Skip this section if you are on a single instance install. If you choose another load
balancing method, make sure you enable sticky sessions. Perform the following steps on your web server (where
you installed your IIS).
First Instance
For the first instance, perform the following steps:
1. Using the Server Manager, navigate to the Features node.
2. Click the Add Features link.
3. Select the Network Load Balancing feature.
4. Click the Next/Install button to install the feature.
5. Launch the Network Load Balancing Manager application.
6. For the first application server, choose the menu path Cluster/New to create a new cluster instance.
7. In the New Cluster: Connect dialog, enter the host name of the current application server in the Host entry
field and click the Connect button.
8. Click the network interface to use for the cluster and click Next.
9. On the New Cluster: Host Parameters dialog, (assuming that a static IP address has been given already for
this interface), there should be an entry in the Dedicated IP addresses section, and the Default state should
be set to Started. Click Next.
10. On the New Cluster: Cluster IP Addresses dialog, click the Add button to add the shared IP address for the
cluster.
11. Enter the appropriate static IP address and subnet mask for the IPv4 address fields. Click OK.
12. On the New Cluster: Cluster Parameters dialog, enter a value for the Full internet name field. Ensure
Cluster operation mode is Unicast. Click Next.
13. On the New Cluster: Port Rules dialog, if required, edit the port rules to restrict the range or instances of port
to 80 (and optionally 443 if HTTPS is to be used). Verify the filtering mode is selected as Multiple host and
Affinity to Single. Click Finish.
Second or Later Instance
For the second or later instance, perform the following steps:
1. Launch the Network Load Balancing Manager application.
34
Getting Started
2. For the second (or later) application server, choose the menu path Cluster/Connect to Existing to create a
new cluster instance.
3. In the Connect to Existing: Connect dialog, enter the host name of the first application server in the existing
cluster into the Host entry field and click the Connect button.
4. In the Clusters section, ensure the existing cluster instance is selected and then click Finish.
5. Ensuring that the cluster instance is selected in the tree-view, choose the context menu, Add Host to Cluster
option.
6. On the Add Host to Cluster: Connect dialog, enter the name of the current application server in the Host
field. Click the Connect button.
7. Click the network interface to use for the cluster and click Next.
8. On the Add Host to Cluster: Host Parameters dialog, (assuming that a static IP address has been given
already for this interface), there should be an entry in the Dedicated IP addresses section, and the Default
state should be set to Started. Click Next.
9. On the Add Host to Cluster: Port Rules dialog, if required, edit the port rules to restrict the range or instances
of port to 80 (and optionally 443 if HTTPS is to be used). Verify the filtering mode is selected as Multiple host
and Affinity to Single. Click Finish.
35
DOM Upgrade
Introduction to DOM Upgrade
This section describes the steps to upgrade your DOM to 1.3.14 while keeping your data and configurations.
WARNING: If you would like to roll back to the DOM version, please perform a backup of the database and the
user data directory before performing the upgrade. The steps for the backup could be found in Data Backup and
Restore. Optionally, you can back up the tsm and tsmapi folder, as well as the catalina folder under
%CATALINA_HOME%\conf folder (for the database connection).
Upgrade from V.1.3.12
Since version 1.3.12, the configuration is stored in the dom-config.properties file that can be found in the
%CATALINA_HOME%\conf directory. The contents of the dom-config.properties file are the same as in version
1.3.14. and are not modified during the upgrade.
If changes were made to either %CATALINA_HOME%\webapps\tsm\WEB-INF\classes\log4j.properties or
%CATALINA_HOME%\webapps\tsmapi\WEB-INF\classes\log4j.properties, make a copy of these files before
upgrading the tsm and tsmapi applications. Restore the backup version of these files after upgrading.
As of version 1.3.14, the database JDBC driver must be downloaded and installed separately. For information on
installing the Java JDBC driver, see Install Java JDBC Driver on page 24.
Upgrade from V.1.3.6
Preserve the previous configurations
There are some changes to the location of configurations in DOM 1.3.14. Prior to the upgrade, please take a note
on the parameters as described below.
1. Open %CATALINA_HOME%\conf\catalina\localhost\tsm.xml in a text editor and locate jdbc/mclv4 resource
tag and
• username
• password
• url
Determine the database used by the DOM by looking at the driverClassName value (mysql or postgresql).
2. Open %CATALINA_HOME%\webapps\tsm\WEB-INF\classes\customapplication.properties in a text editor
and find the following 2 values:
a. PROPERTY_FILE_REPOSITORY_TMP_DIR
bean/account-db1 resource tag. For both resource tag, please note down the following 3 values:
36
DOM Upgrade
b. PROPERTY_DOMAIN_LIC_FILE
3. Go to the DOM admin dashboard (http(s)://<host>/tsm/admin/home.html) and click on Properties. Locate
the property that sets the user data location (eg. c:\tekspeechmanager-data\). If this field does not exist, you
may use the
c:/tekspeechmanager-data/).
4. Extract the dom-config.properties from template that corresponds to the database and open the file in a text
PROPERTY_FILE_REPOSITORY_ROOT in the customapplication.properties (default:
editor. Fill in the database section with 6 values you obtained in step 1.
5. Remove the hash “#” in front of filerepository.tmp.directory and replace the right hand side with value
from step 2a.
6. Remove the hash “#” in front of licensing.licfile.path and replace the right hand side with value from step
2b.
7. Fill in the right hand side of filerepository.shared.root.directory with the value obtained in step 3.
8. Save the file as %CATALINA_HOME%\conf\dom-config.properties.
Update tsm and tsmapi Application
1. Stop Apache Tomcat service either through services.msc or Tomcat service monitor.
2. Move the tsm and tsmapi folder away from %CATALINA_HOME%\webapps folder.
NOTE: Do not just rename the folders in the same directory. These folders must be move out of the
%CATALINA_HOME%\webapps folder.
3. Follow Install Applications on page 24.
4. Remove or move the tsm.xml and tsmapi.xml from %CATALINA_HOME%\conf\catalina\localhost folder.
5. Start Tomcat service.
Upgrade from Version earlier than V1.3.6
Prior to TekSpeech Pro DOM 1.3.6, the setup has been for a single instance. This section describes the steps to
take to upgrade to the latest version while keeping the single instance setup.
Tomcat Application Update
NOTE: The %CATALINA_HOME% refers to the path to the Tomcat directory on your system. The default path is
C:\Program Files\TekSpeech Pro Device and Operator Manager\tomcat.
To update Tomcat:
1. Stop Apache Tomcat service.
2. Perform Tomcat Log Configurations on page 22.
3. Move the tsm and tsmapi folder away from the %CATALINA_HOME%\webapps folder.
Note: Do not just rename the folders in the same directory. These folders must be moved out of the
%CATALINA_HOME%\webapps folder.
4. Follow section Install the tsm and tsmapi Applications on page 24, with these special notes:
a. At Configure Local User Data Location section and Configure Database Connection section, simple just
use the provided
dom-config.properties file and put in tomcat\conf folder.
b. You may skip Configure Webservice Domain on page 26 and later.
dom-config-single-instance.properties file. Rename this file as
37
DOM Upgrade
IIS Reconfiguration
In previous versions of the TekSpeech Pro DOM installation guide, the Jakarta IIS Tomcat connector was used to
redirect JSP and JSPX contents to Tomcat. This section provides the procedure to use Microsoft Application
Request Routing instead. See the note on Using ISAPI Redirector with IIS for reasons for the change.
1. Open IIS Manager and Delete the Tomcat site.
2. Change the binding for Default Web Site to 80.
3. Follow the instructions in Web Server Setup.
4. Restart the IIS server.
38
Data Backup and Restore
Introduction to Data Backup and Restore
To back up the data in TekSpeech Pro DOM, there are two components that need to be backed up when the
application server is stopped: database and user data files. The reason for stopping the application server is to
prevent inconsistency between the database and user data files.
Stop all Tomcat services that access the database and user data files when you are doing either a backup or
restore. If you have a clustered setup, you will need to stop all of them. The database and user data files should be
backed up together and restored together.
Database Backup
MySQL Backup
To perform a MySQL backup:
1. Open a command prompt as an administrator and navigate to the bin folder of your MySQL install, where
mysqldump.exe and mysql.exe are located.
2. Type the following commands:
mysqldump -u[username] -p[password] tsm > tsm.sql
mysqldump -u[username -p[password]] account[account-number] > account[account-number].sql
Replace [username], [password], and [account-number] appropriately.
1. Open both .sql files and add SET foreign_key_checks = 0; as the first SQL command executed and SET
foreign_key_checks = 1; as the final SQL command executed.
2. Save the resulting .sql files.
PostgreSQL Backup
To perform a PostgreSQL backup:
1. Open pgAdmin III and add a connection to the PostgreSQL server with DB owner credentials.
2. Under Databases, right-click the name of the database for DOM DB1 (For example, tsm) and select Backup.
3. Chose the backup file location and name. You can leave the format as custom.
4. Select any other appropriate option as needed and click Backup.
5. Repeat for DB2 (For example, tsmaccount).
39
Data Backup and Restore
User Data Backup
By default, the user data files are stored in c:\tekspeechmanager-data. If TekSpeech Pro DOM was updated from
version 1.2.x, it will contain symbolic links with an absolute path reference. See the section below Contain
Symbolic Links on page 40. Otherwise, if TekSpeech Pro DOM was updated from version 1.3.x, it will not contain
symbolic links. See the section below
Contain Symbolic Links
Perform the following if TekSpeech Pro DOM was updated from version 1.2.x.
Use xcopy with VHD
1. Open Disk Management.
2. Click Action, Create VHD.
3. Follow the wizard to create a VHD with sufficient size for the entire user data directory.
4. Attach the VHD and format the volume. In this section, assume the drive letter for the VHD is E:.
5. Create a directory called UserDataBackup under E:.
6. Open a command prompt as a local administrator and execute the following command:
xcopy /B /E c:\tekspeechmanager-data\*.* E:\UserDataBackup\
No Symbolic Link on page 40.
1. When all files are transferred, you may detach the VHD and store the file.
No Symbolic Link
Perform the following if TekSpeech Pro DOM was updated from version 1.3.x.
Either copy the entire
location.
c:\tekspeechmanager-data folder to the backup location or zip the contents to the backup
Database Restore
This section contains information on how to restore the database from backup files.
WARNING: A database with a newer schema (For example, with TekSpeech Pro DOM 1.3.6) is not backward
compatible with older versions of TekSpeech Pro DOM (For example 1.2.7). You may have an older database
schema attaching to a newer version of DOM.
MySQL Restore
To perform a MySQL restore:
1. Locate the backup .sql file.
2. Open a command prompt as an administrator and navigate to the bin folder of the MySQL install.
3. Verify the backup .sql file turns the foreign key check off before restoring and turns the check back on after the
restore.
4. Type the following commands:
mysql.exe -u[root] -p[password] -e "drop database tsm"
mysql.exe -u[root] -p[password] -e "create database tsm"
mysql.exe -u[username] -p[password] tsm < [full path to your tsm backup file]
mysql.exe -u[root] -p[password] -e "create database account[account-number]"
mysql.exe -u root -p[password] account[account-number] < account[account-number].sql
40
Data Backup and Restore
Replace [username], [password], and [account-number] appropriately.
PostgreSQL Restore
To perform a PostgreSQL restore:
1. Open pgAdmin III and add a connection to the PostgreSQL server with DB owner credentials.
2. Under Databases, right-click the name of the database you want to restore and then click Restore.
If you do not have a database that already exists, you may create one at this time by right-clicking Databases
and New Database.
3. Select the database file that you want to restore from.
4. Choose any other appropriate option as needed and click Restore.
5. Repeat for each additional database to restore.
6. If you are moving the databases between servers, make sure that you also restore the login roles for
TekSpeech Pro DOM.
User Data Restore
Restore from Zip
Extract the content of the archive to your destination user data folder. By default, this path is
c:\tekspeechmanager-data\
Restore from VHD
To restore from VHD:
1. Mount the VHD through Disk Management. This section assumes the mounted drive letter is E:.
2. Open a command prompt as a local administrator and type in the following:
xcopy /B /E E:\ UserDataBackup \*.* C:\tekspeechmanager-data\
1. Once the transfer is complete, you may detach the VHD.
41
Rollback to Previous Version
Introduction to Rollback to Previous Version
Rollback of the TekSpeech Pro DOM application can be achieved only if you kept the older version of the database
backup and the user data folder. The reason for this is the newer version of the database is not backward
compatible to the older version of TekSpeech Pro DOM. Although the installation of TekSpeech Pro DOM 1.3.6 is
vastly different from previous versions, the web server setup can be kept the same across different versions.
Install the Older Version
The only component that is changed from version to version is the TekSpeech Pro DOM application (For example,
tsm and tsmapi). To restore the TekSpeech Pro DOM to an older version, replace
webapps\tsmapi with the content of tsm.war and tsmapi.war, respectively. If you made any changes in these two
folders, (For example, a logging change), then you need to reapply them. Keep in mind that the user data folder
location is
c:\tekspeechmanager-data for older versions and the domain.lic file needs to be in that folder.
webapps\tsm and
Restore the Database and User Data Folder
After the installation of the previous TekSpeech Pro DOM application, the database and user data need to match
with the version of TekSpeech Pro DOM. With Tomcat service stopped, restore the database and user data
according to section Introduction to Data Backup and Restore on page 39 from your backup files.
42
Setup Verification
Introduction to Verifying Your Setup
After you have fully configured TekSpeech Pro DOM, verify the installation and configuration were successful by
performing the following actions in TekSpeeck Pro DOM:
• Deployment of an existing configuration (if TekSpeech Pro DOM was upgraded)
• Deployment of a new configuration (with a new application)
• Login on the terminal.
Troubleshooting
“Connection Error" or Deployment Failure
Check your virtual directory configuration and URL rewrite rule for the file. If it is configured properly, you should be
able to download the PDK file and configuration file using the browser. For example,
C:\tekspeechmanager-data\files\[Lic_number]\applications\[app_name].pdk can be downloaded using the
http://[host]/tsmapi/file/files/applications/[app_name].pdk.
link
Unable to Login - Keeps Showing Me the Logon Page
Most likely you have clustered application servers. Verify your NLB affinity setting and ARR affinity setting is
correct.
500 level Error
The Tomcat server is not ready for requests.
Not Responding or Page Not Found after Clicking on the Account icon at Admin Page
Please make sure the application server has access to the license server and the reference data server as outlined
in the requirement section of application server. Double check your firewall rules/proxy settings.
43
Version Information
TekSpeech Pro DOM Version Information
This section points out the changes between versions that may affect the setup.
Version 1.3.14
• Fixed issue operator password stored as encrypted value in database
• Fixed issue delete site not allowed unless all related data to that site is deleted first
• Fixed issue related to encoding of voice logs files
• Fixed issue related to moving operator to a different site and updating link to a speech profile
• New feature DOM health check
• Fixed issue operator login status consistency
Version 1.3.12
• Support for license replacement
• Added cleanup policy for user data and database
• Added license server connection status
• Support for TekSpeech Pro V4
• Updated browser support for Internet Explorer 11
• Fix for operator voice logging issue when logs exceed a certain size
• Updated Tomcat support
• Fixed update policy for user data folder to remove symbolic links
• Fixed deleting files through admin dashboard\files
• Added license server connection status
• Improved English and French localization
• General performance improvements
• Fixed issue related to multiple active deployment plans for the same group
Version 1.3.6
• Support for configurable location of user data folder.
• Support for configurable location of domain.lic file and temp directory.
44
Version 1.3.2
• Initial support for PostgreSQL database.
• No longer using symbolic links in the user data.
Version 1.2.7
• Support for HTTP proxy.
Version 1.2.6
• Initial release.
Getting Started
45
www.zebra.com
Loading...