TIBCO Spotfire Server 3.2.2 - TIBCO Product Documentation

TIBCO Spotfire ® Server 3.2.2 

Installation and Configuration Manual 

Revision date: 14 February 2012

Important Information 

SOME TIBCO SOFTWARE EMBEDS OR BUNDLES OTHER TIBCO SOFTWARE. USE 

OF SUCH EMBEDDED OR BUNDLED TIBCO SOFTWARE IS SOLELY TO ENABLE 

THE FUNCTIONALITY (OR PROVIDE LIMITED ADD-ON FUNCTIONALITY) OF THE 

LICENSED TIBCO SOFTWARE. THE EMBEDDED OR BUNDLED SOFTWARE IS NOT 

LICENSED TO BE USED OR ACCESSED BY ANY OTHER TIBCO SOFTWARE OR 

FOR ANY OTHER PURPOSE. 

USE OF TIBCO SOFTWARE AND THIS DOCUMENT IS SUBJECT TO THE TERMS 

AND CONDITIONS OF A LICENSE AGREEMENT FOUND IN EITHER A SEPARATELY 

EXECUTED SOFTWARE LICENSE AGREEMENT, OR, IF THERE IS NO SUCH 

SEPARATE AGREEMENT, THE CLICKWRAP END USER LICENSE AGREEMENT 

WHICH IS DISPLAYED DURING DOWNLOAD OR INSTALLATION OF THE 

SOFTWARE (AND WHICH IS DUPLICATED IN 

LICENSE_TIBCOSPOTFIRESERVER.PDF) OR IF THERE IS NO SUCH SOFTWARE 

LICENSE AGREEMENT OR CLICKWRAP END USER LICENSE AGREEMENT, THE 

LICENSE(S) LOCATED IN THE "LICENSE" FILE(S) OF THE SOFTWARE. USE OF 

THIS DOCUMENT IS SUBJECT TO THOSE TERMS AND CONDITIONS, AND YOUR 

USE HEREOF SHALL CONSTITUTE ACCEPTANCE OF AND AN AGREEMENT TO BE 

BOUND BY THE SAME. 

This document contains confidential information that is subject to U.S. and international 

copyright laws and treaties. No part of this document may be reproduced in any form without 

the written authorization of TIBCO Software Inc. 

TIBCO and Spotfire are either registered trademarks or trademarks of TIBCO Software Inc. 

and/or subsidiaries of TIBCO Software Inc. in the United States and/or other countries. All 

other product and company names and marks mentioned in this document are the property of 

their respective owners and are mentioned for identification purposes only. This software may 

be available on multiple operating systems. However, not all operating system platforms for a 

specific software version are released at the same time. Please see the readme.txt file for the 

availability of this software version on a specific operating system platform. 

THIS DOCUMENT IS PROVIDED “AS IS” WITHOUT WARRANTY OF ANY KIND, 

EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED 

WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, 

OR NON-INFRINGEMENT. THIS DOCUMENT COULD INCLUDE TECHNICAL 

INACCURACIES OR TYPOGRAPHICAL ERRORS. CHANGES ARE PERIODICALLY 

ADDED TO THE INFORMATION HEREIN; THESE CHANGES WILL BE 

INCORPORATED IN NEW EDITIONS OF THIS DOCUMENT. TIBCO SOFTWARE INC. 

MAY MAKE IMPROVEMENTS AND/OR CHANGES IN THE PRODUCT(S) AND/OR 

THE PROGRAM(S) DESCRIBED IN THIS DOCUMENT AT ANY TIME. 

Copyright © 1996 - 2012 TIBCO Software Inc. ALL RIGHTS RESERVED. 

THE CONTENTS OF THIS DOCUMENT MAY BE MODIFIED AND/OR QUALIFIED, 

DIRECTLY OR INDIRECTLY, BY OTHER DOCUMENTATION WHICH ACCOMPANIES 

THIS SOFTWARE, INCLUDING BUT NOT LIMITED TO ANY RELEASE NOTES AND 

"READ ME" FILES. 

TIBCO Spotfire is covered by U.S. Patent No. 6,014,661 and U.S. Patent No. 7, 216,116. 

Other patent(s) pending. 

TIBCO Software Inc. Confidential Information 

2 (144) TIBCO Spotfire® Server 3.2.2

Contents 

1 Installation Planning 6 

1.1 Overview 6 

1.2 Architectural Overview 6 

1.3 Migration and Upgrade 8 

1.4 Conceptual Outline of Installation Process 9 

1.5 Pre-Installation Checklist 10 

2 Installing Spotfire Server 3.2 16 


2.2 Prepare the Database 16 

2.3 Install Spotfire Server 22 

2.4 Install the Configuration Console 26 

2.5 Run Spotfire Server as Domain User 28 

2.6 Install Patches 29 

3 Migration from 10.1 30 


3.2 Prerequisites 31 

3.3 Install the Migration Tool 31 

3.4 Set up Database Connection File 31 

3.5 Run the Migration Tool 32 

3.6 Database Drivers 34 

3.7 Log Files 35 

3.8 Restoring a Spotfire 3.2 Database 35 

3.9 Configuration Not Migrated 36 

3.10 Uninstall the Migration Tool 36 

4 Upgrade from 3.0 or 3.1 to 3.2 37 


4.2 Back up or Clone the 3.0 or 3.1 Database 37 

4.3 Run the Upgrade Tool 38 

4.4 Default Join Database 46 

4.5 Start the Spotfire Server 46 

4.6 Verify Configuration 46 

5 Configure the System 47 


5.2 Spotfire System Security 47 

5.3 Database Drivers 47 

5.4 Starting the Spotfire Server Controller 48 

5.5 Starting the Configuration Console 50 

5.6 Setting up Authentication 51 

5.7 Setting up User Directory 52 

5.8 Add Server to Cluster 53 

5.9 Start All Servers 54 

5.10 Setting up Shared Disk Location 54 

5.11 Making the Demo Database Available 54 

5.12 Assign Admin User 54 

TIBCO Spotfire® Server 3.2.2 3 (144)

6 Spotfire Administrative Tasks 56 


6.2 TIBCO Spotfire Administration Tools 56 

6.3 Deploying TIBCO Spotfire 57 

6.4 Setting up Users, Groups, and Licenses 57 

6.5 Importing Library Content 58 

7 Load Balancing 59 


7.2 Prerequisites 59 

7.3 Cluster Node Configuration 59 

7.4 Load Balancer Configuration 60 

7.5 Kerberos Authentication 61 

7.6 X.509 Client Certificate Authentication 62 

7.7 NTLM Authentication 62 

7.8 Load Balancer Authentication 63 

7.9 Load Balancer AJP Keyword Restriction 63 

8 Authentication and User Directory 65 


8.2 Username and Password Authentication 65 

8.3 Single Sign-on Authentication 68 

8.4 User Directory 79 

9 Advanced Procedures 84 


9.2 Installing Spotfire Server Silently Using Pre-defined Parameters 84 

9.3 Setting up HTTPS on a Spotfire Server 86 

9.4 Restricting Access to the Configuration Console 89 

9.5 Configuring LDAPS 91 

9.6 Database Authentication using Kerberos 91 

9.7 Creating and Installing a Self-Signed Client Certificate 95 

9.8 Setting up HTTPS in a Load Balanced Environment 97 

9.9 Forwarding Traffic from the Load Balancer to the Configuration Console99 

9.10 Shared Disk Location in a Clustered Environment 100 

9.11 Preventing User Directory Synchronization 101 

9.12 Configuring X.509 Client Certificates in a Load Balanced Environment101 

9.13 Running Database Preparation Scripts Manually 102 

9.14 Resizing Temporary Tablespace 103 

9.15 Modifying the Virtual Memory 103 

9.16 Starting and Stopping the Spotfire Server 104 

9.17 Data Source Templates 106 

9.18 Default Join Database 121 

9.19 Login Behavior 122 

9.20 Impersonation 125 


10 Backup and Restore 128 


11 Technical Reference 131 



11.1 Server Logs and Diagnostics 131 

11.2 Server.xml 135 

11.3 krb5.conf 137 

11.4 Database Connection Configuration 138 

12 Uninstall 143 

12.1 Server Software Uninstall 143 

12.2 Database Removal 143 


Installation Planning 

1 Installation Planning 

1.1 Overview 

TIBCO Spotfire Server provides basic infrastructure, which is used by the TIBCO 

Spotfire and TIBCO Spotfire Web Player clients. 

TIBCO Spotfire Server has functionality for identifying users and assigning 

privileges, serves as a central storage for program updates, is a central repository for 

analysis files, and connects to different external data sources. 

TIBCO Spotfire Server can be installed on one machine, or be clustered on several 

machines, thus providing load balancing and failover support. 

1.2 Architectural Overview 

Spotfire Server can be installed in two different ways. The simplest way is a one server 

solution, illustrated with the following picture: 

The Spotfire Server serves requests from clients while communicating with the 

database. It may also redirect authentication requests from clients to an authentication 

service, if present. Read more about authentication services in the chapter 

“Authentication and User Directory” on page 65. The Spotfire database holds 

information about its environment and users. Also, users can store analyses in the 

databases and share them with others. 



The Web Player server communicates with the Spotfire Server much like it does with a 

Spotfire client. The Web Player provides a subset of the Spotfire features specialized 

for viewing in a standard web browser, by which users can access the Web Player. 

Also installed on the Spotfire Server is the Spotfire Configuration Console. This is a 

web-based application used by administrators to configure and manage the system. 

Read more about the configuration console in the chapter “Install the Configuration 

Console” on page 26. 

It is also possible to deploy Spotfire Server in a multi-server environment. In this 

scenario, several Spotfire Servers are installed, each communicating with the same 

database. The clients communicate with a load balancer that has information about the 

different servers. It forwards calls from clients to an available server and makes sure 

the answers get back to the client. 

The recommended way to load balance a Spotfire system is based on a model using a 

combination of the Apache httpd, its module mod_jk, and the ability of Apache 

Tomcat applications to communicate with such a machine. It is possible to use a 

different load balancer, as long as it supports session affinity. Read more about load 

balancing in the chapter “Load Balancing” on page 59. 

In this example, the configuration console is installed on a separate machine. 

However, it could instead be installed on one or more of the Spotfire Servers in your 

system according to your preferences. 



Note that even if you have only one Spotfire Server, this is still considered as part of a 

cluster consisting of one server. This can be seen in every view in the configuration 

console, and it is possible to add more servers to the Spotfire system in the future, if 

expansion of the Spotfire system is needed. 

The software distributed with Spotfire Server consists of three main components 

running as Apache Tomcat web applications: the Spotfire Server, the Spotfire Server 

Controller, and the Configuration Console. In a non-clustered environment, all three 

run within the same instance of Tomcat, as this illustration shows: 

In our example of a clustered environment where Spotfire Server is installed on two 

machines, and the configuration console is installed on a separate machine, this can be 

illustrated as follows: 

The Spotfire controller is the process that is first started when the Spotfire Server 

Windows Service is started or Unix startup script is run. It starts and stops the Spotfire 

Server Tomcat web application process. It also listens to traffic from the configuration 

console application. The configuration console provides a web-based interface to 

system configuration and administration. 

1.3 Migration and Upgrade 

When installing Spotfire Server 3.2, always begin by preparing a database and 

installing Spotfire Server software. If you have been running Spotfire before, you may 

then perform a migration or an upgrade to transfer information from your previous 

installation to your new 3.2 installation. The concepts of migration and upgrade are 

similar, yet take slightly different approaches. 

Migration 

If you are running Spotfire Analytics Server 10.1, you can perform a migration to 

Spotfire Server 3.2. This entails installing and running the Migration Tool, distributed 

with the Spotfire Server. This tool will extract information from a running 10.1 

database and insert it into a 3.2 database. It will also extract Library information and 

put it into export files that you can later import to the 3.2 database. The 10.1 database 

is never written to when you perform a migration. 

Upgrade 



If you are running Spotfire Server 3.0 or 3.1, you can perform an upgrade to Spotfire 

Server 3.2. This entails running the Upgrade Tool, distributed with the Spotfire Server. 

This tool will modify the 3.0 or 3.1 database so that the 3.2 server can read and write 

from and to it, and also copy configuration from a 3.0 or 3.1 server installation. 

Additionally, the Upgrade Tool can also read information from an already installed 3.2 

server. Because the Upgrade Tool modifies an existing database, it is important that 

you back up the 3.0 or 3.1 database, or make a copy of it and perform the upgrade on 

this copy. 

1.4 Conceptual Outline of Installation 

Process 

Each step outlined below is explained in detail in “Installing Spotfire Server 3.2” on 

page 16. You should read through that chapter as well as this outline before you 

attempt an installation. 

1 Read the “Pre-Installation Checklist” on page 10 and write down the needed 

information. 

2 Prepare the Spotfire database. If you are upgrading from 3.0 or 3.1 this includes 

backing up or cloning the existing database. If you are performing a fresh install or 

migrating from 10.1, this includes creating new database tables. 

3 Run the Spotfire Server installer on all intended machines. 

4 Install the latest patch, if any, released for Spotfire Server since its release. 

5 If needed, replace DataDirect database drivers shipped with Spotfire with native 

database drivers from your database vendor. 

6 If you are performing a migration from 10.1, run the migration tool. If you are 

performing an upgrade from 3.0 or 3.1, run the upgrade tool. 

7 Log into the configuration console. 

8 If you have upgraded from 3.0 or 3.1, verify that the configuration is intact. If you 

have performed a new install or a migration from 10.1, configure the system regarding 

authentication, user directory, etc. 

9 Add servers to cluster or verify that all upgraded servers are in the cluster. 

10 If load balancing is to be used, set up a load balancer and configure it to communicate 

with the Spotfire Servers. 

11 Assign the first Spotfire Admin. You will need the unlock code located in the file 

codes.txt distributed with the Spotfire Server. 

The Spotfire Server is now up and running. Next, a number of administrative tasks 

need to be performed before the users can use the Spotfire system. These tasks are 

described in the TIBCO Spotfire - Deployment and Administration Manual 

distributed with the TIBCO Spotfire Deployment. 



1.5 Pre-Installation Checklist 

Before you begin installing Spotfire Server 3.2, there are certain things you must 

determine. Below is a series of checklists that you must provide answers to before 

starting the installation. 

Database 

You must have a database server up and running before you install Spotfire Server. 

The Spotfire Server installer will not install a database server, you must provide one 

yourself. It is recommended that you run this on a separate and dedicated machine. 

Spotfire supports Microsoft SQL Server and Oracle database engines. 

When installing Spotfire Server, you will run a number of scripts distributed with the 

installer that will create and prepare a database. Further specifications about this can 

be found in the chapter “Prepare the Database” on page 16. 

Note: If you are running Spotfire Analytics Server 10.1, note that you must create a 

new database with unique user credentials for Spotfire Server 3.2. You cannot reuse 

the same database or any of its tables. Also note that if you are running the 10.1 

database in Oracle XE, there are certain limitations of this database engine you need to 

be aware of. 

What type of database server and version will 

you be using with your Spotfire Server? 

Spotfire Server supports the database servers 

listed on the system requirements web page: 

(http://support.spotfire.com/sr.asp) 

What is the hostname of the database server? 

What are the administrator username and 

password for the database server (If you do 

not wish to write sensitive information here, 

make sure to memorize it)? 

What is the SID (Oracle) or the Instance 

(MSSQL) name of the database server you 

will be using? 



When you set up the Spotfire database, you will create database users and databases. It 

is recommended that you decide what to name these now. 

What will be the name of the Spotfire 

database (MSSQL only)? 

What will be the name of the Spotfire 

database user? 

Note: If the database is using Windows 

Integrated Authentication, make note of this 

user. If you use Integrated Authentication, the 

Spotfire Server must run as this Windows 

Domain user. If the Spotfire Server needs to 

authenticate with other databases 

(Information Sources) using Integrated 

Authentication, it will only be possible to 

authenticate using the Windows user the 

Spotfire server runs as. 

What will be the password of the Spotfire 

database user? 

Server Details 

Spotfire Server 3.2 can be installed on one or more machines, each one storing 

information in the same database. If you install more than one server, you can use a 

separate computer as a load balancer to redirect calls from clients to an available 

server. This will improve performance if you have many users, and will also make use 

of fail-over functionality, which is convenient if you, for instance, need to take one or 

more servers offline for maintenance. 

The Spotfire servers are always organized in a cluster, even if you have only one 

server. You can install more servers and add to your cluster at any time. 

For more information, see “Architectural Overview” on page 6. 

For comprehensive system requirements refer to http://support.spotfire.com/sr.asp. 

Always check here to find updated and precise specifications. 



How many Spotfire Servers are you going to 

install? 

What will you call the cluster that the 

server(s) will belong to? 

What is (are) the hostname(s) of the intended 

Spotfire Server machine(s)? 

Note: The hostnames cannot contain the 

character “_” (underscore). If it does, you 

will need to change the names before you 

install. 

What is the hostname of the intended 

Configuration Console machine (may be a 

separate machine or any Spotfire Server 

machine)? 

If you intend to install a load balancer, what 

is the hostname of it? 

What operating system(s) are you going to 

install Spotfire Server and Configuration 

Console on? 

Spotfire Server can be installed on Windows 

Server 2003, 2008, and 2008 R2, Solaris 9 

and 10 (SPARC-based editions), Red Hat 

Enterprise Linux 4 and 5, and SUSE Linux 

Enterprise 9 and 10. 

Ports 

The Spotfire Server installer will ask for three listen ports to be used by three different 

applications: Spotfire Server, Configuration Console, and Spotfire Controller. Each of 

these applications are described in the section “Architectural Overview” on page 6. 

If you are installing Spotfire Server on a machine that is already running other 

applications you must ensure that you do not select any port that is already in use by 

these applications. 

If you already have Spotfire Analytics Server 10.1 or Spotfire Server 3.0 or 3.1 

installed on a machine, and intend to install Spotfire Server 3.2 on the same machine, 

note that the 10.1 or 3.0 or 3.1 server is already using three ports. You must ensure that 

you do not select the same ports for the 3.2 server. 

Note: Selecting a port already in use may result in failure to start one or more of the 

servers... 



Which port number will be used for the 

Spotfire Server port? 

(Default: 80) 


Configuration Console port? 

(Default: 8080) 


Spotfire Controller port? 

(Default: 8078) 

Authentication and User Directory 

Authentication is when users prove to the system who they are. The user directory is 

where the Spotfire system stores user and group names used to set and verify 

permissions. The Spotfire system is able to authenticate users internally or with 

external sources. User directory information may be synchronized with an external 

source. These settings are called authentication methods and user directory methods, 

respectively. Which methods and combinations to select depends entirely on factors 

such as number of users and what kind of infrastructure already exists in the network 

in which Spotfire is used. 

It is vital that you have a clear idea of which authentication and user directory 

alternatives you wish to set up. Also note that certain alternatives will require you to 

have a solid knowledge of how that technology works. 

This manual explains how to set up Spotfire Server to work with various 

authentication and user directory sources, but many of these must already be in place 

and working in your organization before you attempt to install Spotfire Server. This 

manual will not explain how to configure these sources, only how to connect to them. 

For example, if you intend to set up Spotfire Server to authenticate with an LDAP 

system, then you must know how that LDAP system is set up in your organization. If 

you do not, then you must get assistance from someone in your organization that is 

responsible for that system. 

To help you select an authentication and user directory combination, please see 

“Authentication and User Directory” on page 65. 



Authentication 

Will you use any type of username and 

password login? If so, which type? Valid 

options are 

• Spotfire Database 

User Directory 

• LDAP 

• Windows NT Domain 

• Custom JAAS 

Will you use any type of single sign-on 

login? If so, which type? Valid options are 

• Kerberos 

• X.509 Client Certificate 

• NTLM 

Note: Single sign-on is not possible with the 

Spotfire Database authentication method. 

If you will use any login method other than 

Spotfire Database you need extensive 

knowledge of that authentication method, and 

how it is set up in your organization. 

If you do not have this, you should write 

down the name and contact information of 

someone who can assist you with this. 

Which User Directory method will you use? 

Valid options are 


• LDAP 


If you will use any User Directory method 

other than Spotfire Database you need 

extensive knowledge of this authentication 

method, and how it is set up in your 

organization. 

If you do not have this, you should write 

down the name and contact information of 

someone who can assist you with this. 



Before you continue with the installation of Spotfire Server, you should make sure to 

write down all the information in the tables above. 


Installing Spotfire Server 3.2 

2 Installing Spotfire Server 3.2 

2.1 Overview 

This chapter explains how to install Spotfire Server 3.2. Please perform the following 

instructions carefully: 

MIGRATING OR UPGRADING? 

Important: Before you start the installation process below, make sure 

you have backups of the 10.1 or 3.0 or 3.1 server software and 

databases. For an explanation of the distinction between migration and 

upgrade see the section “Migration and Upgrade” on page 8. 

2.2 Prepare the Database 

2.2.1 Prerequisites 

Before you begin installing Spotfire Server, make sure your database server complies 

with the latest system requirements at: 

http://support.spotfire.com/sr.asp 

2.2.2 Upgrading from Spotfire Server 3.0 or 3.1 

UPGRADING FROM 3.0 OR 3.1 TO 3.2? 

If you are running Spotfire Server 3.0 or 3.1, do not run the database 

preparation scripts described below. Continue to “Install Spotfire 

Server” on page 22 and follow the instructions there. Once you have 

the 3.2 server installed, run the Upgrade tool to upgrade your database. 

2.2.3 Overview 

Before you can run the Spotfire Server installer, you must set up the Spotfire Database 

used to manage users and groups, and optionally the Spotfire Demo Database which 

contains some demo data and analyses. This is done by running a few scripts. 

However, these must first be modified to suit your system. 

You can use either an Oracle database server or a Microsoft SQL Server to hold your 

Spotfire Server Database. Depending on your choice, please continue to either: 

• “Oracle” on page 17 

• “Microsoft SQL Server” on page 19. 



2.2.4 Oracle 

2.2.4.1 Prerequisites 

In order for the scripts to work, and for the Spotfire Server to be able to communicate 

with the databases once installed, the following settings must be configured on the 

Oracle Server: 

• The Oracle Server must allow for username and password authentication. 

• National Language Support (NLS) must be set to match the language in which 

you will store data (affects search). 

If the database server NLS cannot be set to match the language in which you will store 

data, Oracle provides other methods of setting NLS to a specific database or user, such 

as per session. Refer to the Oracle database documentation for more information about 

this.. 

MIGRATING FROM 10.1 TO 3.2? 

If you are using an Oracle XE server to store the 10.1 databases, and 

intend to use the same database server to store the 3.2 database, you 

must begin by modifying the Oracle XE configuration. Specifically, 

you need to set how connections are monitored. You do this by 

executing the SQL command 

ALTER SYSTEM SET PROCESSES=150 SCOPE=SPFILE; 

using the Oracle administration tool you normally use. You must restart 

the Oracle XE TNS listener after you have done this. It is important that 

you do this before preparing the 3.2 database and migrating the 10.1 

data to it. 

Note: It is strongly recommended that you do not store the Spotfire 

Server 3.2 database on an Oracle XE database server. You should 

upgrade to a supported production version of Oracle. 

2.2.4.2 Copy the Scripts to the Database Server 

1 On the installation media, find the scripts directory: 

• scripts/oracle_install 

2 Copy the entire directory to your database server. 

Comment: The commandline database tools (sqlplus, sqlload, etc) must be in the 

system path of the database server. 



2.2.4.3 Modify the create_databases Script 

In the folder you just copied, you will find a file called create_databases.bat 

(Windows) or create_databases.sh (Solaris/Red Hat Enterprise Linux/SUSE Linux 

Enterprise). 

1 Open this file in a text editor. 

2 Find the rows: 

set ROOTFOLDER= 

set CONNECTIDENTIFIER= 

set ADMINNAME=system 

set ADMINPASSWORD= 

set SERVERDB_USER= 

set SERVERDB_PASSWORD= 

set SERVER_DATA_TABLESPACE=SPOTFIRE_DATA_32 

set SERVER_TEMP_TABLESPACE=SPOTFIRE_TEMP_32 

rem Demo data parameters 


set INSTALL_DEMODATA=yes 

3 Specify these variables. 

• ROOTFOLDER. This is where the tablespaces will be created, thus it must be a 

directory that is writable for the Oracle instance, usually / 

oradata/. 

• CONNECTIDENTIFIER. This is the Oracle TNS name of the database. 

• ADMINNAME. This is the name of a user with admin privileges on the 

database. Defaults to the default system account. 

• ADMINPASSWORD. This is the password of the above user. 

• SERVERDB_USER. This is the user that will be created and used to set up the 

Spotfire database. 

• SERVERDB_PASSWORD. This is the password of the above user. 

• SERVER_DATA_TABLESPACE. This is the name of the tablespace that will be 

created. The default value should work for most systems. 

• SERVER_TEMP_TABLESPACE. This is the name of the temporary tablespace 

that will be created. The default value should work for most systems. 

• INSTALL_DEMODATA. This controls whether or not the demo database will 

be created. Set to “no” if you do not wish to create it. The default is “yes”. 

All the variables must be set to new and unique names. If you wish to create the demo 

database, do not change the default username and password. 

Note: If you install the demo database, you need to perform additional steps to make 

the data available to the users. Please see the the section “Making the Demo Database 

Available” on page 54 for more information on how to do this. 

4 Save the file and exit the editor. 



The demo database contains example data that is useful for learning about Spotfire. If 

the users are new to Spotfire, you might want to install it. 

Note: If you are creating the Spotfire tablespaces on a database server that is already 

hosting Analytics Server 10.1 or Spotfire Server 3.0 or 3.1 tablespaces, ensure that you 

do not select any names for the 3.2 databases and users that conflict with the 10.1, 3.0, 

or 3.1 tablespaces and users. 

2.2.4.4 Run the create_databases.bat/.sh Script 

Once the scripts have been properly set up, run the create_databases.bat (or 

create_databases.sh) script. Running this script will execute all of the other SQL 

scripts in the folder. 

1 Open a command prompt window. 

2 Navigate to the directory where you placed the scripts. 

3 Type create_databases.bat and press Enter. 

Response: The scripts now set up the Spotfire Database needed to run Spotfire 

Server, and the Spotfire Demo Database which contains demo data. Note 

that this may take some time. 

A log file called log.txt will be created in the same directory as the create_databases 

file. Also, a number of log files from the creation of the Spotfire demo data will be 

created. Please examine these files to verify that no errors occurred. 

Proceed to “Install Spotfire Server” on page 22 when finished. 

2.2.5 Microsoft SQL Server 

2.2.5.1 Prerequisites 

In order for the scripts to work the following settings need to be configured on the 

Microsoft SQL Server: 

• TCP/IP communication must be enabled. 

• A TCP/IP listener port must be configured (The recommended default is 1433). 

• A case insensitive collation must be used (at least for the Spotfire database). 

• Collation must match the language in which you will store data (affects search). 

2.2.5.2 Copy the Scripts to the Database Server 

1 On the installation media, find the scripts directory: 

• scripts/mssql_install 



2 Copy this entire directory to a temporary place on the local disk of your intended 

database server. 

Comment: The commandline database tools (sqlcmd etc) must be in the system path 

of the database server. 

2.2.5.3 Modify the create_databases.bat Script 

In the folder you just copied you will find two files called create_databases.bat and 

create_databases_ia.bat. If you are using Windows Integrated Authentication (ia) on 

your Microsoft SQL Server, use the second one. Otherwise, use the first one. 

Note: Windows Integrated Authentication requires additional steps. See the section 

“Run Spotfire Server as Domain User” on page 28 for more information about this. 


2 Find the rows: 

set CONNECTIDENTIFIER=\ 

set ADMINNAME=sa 

set ADMINPASSWORD= 

set SERVERDB_NAME=spotfire_server32 

set SERVERDB_USER= 

set SERVERDB_PASSWORD= 


set INSTALL_DEMODATA=yes 

Note: If you are using Windows Integrated Authentication, the 

create_server_user_ia.sql script will create a database user (SERVERDB_USER) for 

the server database (SERVERDB_NAME). The database user is then tied to the SQL 

Server login named WINDOWS_LOGIN_ACCOUNT. 

3 Specify these variables. 

• CONNECTIDENTIFIER. Set this by replacing with the name of 

the server running the SQL Server instance, and replacing 

with the name of the SQL Server instance. 

• ADMINNAME. This is the name of a user with admin privileges on the 

database, most often sa. This is not used if you are using Windows Integrated 

Authentication. 

• ADMINPASSWORD. This is the password of the above user. This is not used if 

you are using Windows Integrated Authentication. 

• SERVERDB_NAME. This is the name of the database that will be created. 

• SERVERDB_USER. This is the user that you wish to create and use for this 

database. 

• SERVERDB_PASSWORD. This is the password for the above user. This is not 

used if you are using Windows Integrated Authentication. 



• INSTALL_DEMODATA. This controls whether or not the demo database 

should be created. Set to “no” if you do not wish to create it. The default is 

“yes”. 

• WINDOWS_LOGIN_ACCOUNT. This is the Windows Login Account that is 

used to authenticate with the database server. This is not used if you are using 

database authentication. 

Note: When using Windows Integrated Login, the create_server_user_ia.sql script 

will create a database user with the name specified in the 

WINDOWS_LOGIN_ACCOUNT. By default, it is assumed that a Windows login 

with this name already exists. If it does not and you wish to create such a login, open 

the script in a text editor and uncomment the section that reads 

/* 

use master 

GO 

CREATE LOGIN [$(WINDOWS_LOGIN_ACCOUNT)] FROM WINDOWS WITH 

DEFAULT_DATABASE=[$(SERVERDB_NAME)], DEFAULT_LANGUAGE=[us_english] 

GO 

ALTER LOGIN [$(WINDOWS_LOGIN_ACCOUNT)] ENABLE 

GO 

DENY VIEW ANY DATABASE 

TO [$(WINDOWS_LOGIN_ACCOUNT)] 

*/ 

If you wish to create the demo database, do not change the default database name, 

username, and password. Make sure that the database server does not have a database 

or a user with these names already. 

Note: If you install the demo database, you need to perform additional steps to make 

the data available to the users. Please see the the section “Making the Demo Database 

Available” on page 54 for more information on how to do this. 


The demo database contains example data that is useful for learning about Spotfire. If 

the users are new to Spotfire, you might want to install it. 

Case Sensitive Collation 

If your database server is set to use a case sensitive collation by default, you must also 

specify that the Spotfire database should be case insensitive. To do this, you must edit 

the SQL script create_server_db.sql: 


2 Find the commented out line 

--create database $(SERVERDB_NAME) collate Latin1_General_CI_AS; 

3 Remove the leading “--”. Set the collation to the collation of your preference, and 

make sure it is case insensitive (CI), for example Latin1_General_CI_AS. (Refer to the 



Microsoft SQL Server documentation for more information about available 

collations). 

4 Comment out the line below it: 

--create database $(SERVERDB_NAME) 


2.2.5.4 Run the create_databases Script 

Once the scripts have been properly set up, run the create_databases.bat or 

create_databases_ia.bat script. Running this script will execute all of the other sql 

scripts in the folder. 

1 Open a command prompt window. 

2 Navigate to the directory where you placed the scripts. 

3 Type create_databases.bat or create_databases_ia.bat and press Enter. 

Response: The scripts now set up the database table needed to run Spotfire Server. 

Note that this may take some time. 

A number of log files will be created in the same directory as the create_databases file. 

Please examine these files to verify that no errors occurred. 

Proceed to “Install Spotfire Server” on page 22 when finshed. 

2.3 Install Spotfire Server 


Before you begin installing Spotfire Server, make sure your intended machine 

complies with the system requirements. 

http://support.spotfire.com/sr.asp 


The Spotfire Server installer lets you install two components: 

• The Spotfire Server 

• The Spotfire Configuration Console 

Depending on how you want to set up your system, you can select to install both these 

applications on the same machine, or if you prefer, you can choose to install them on 

separate machines. 



If you plan to run only a single Spotfire Server, you will most likely install both the 

Spotfire Server and the Spotfire Configuration Console on the same machine. In a 

clustered environment with several Spotfire Servers, it is often preferable to install the 

configuration console on a separate machine. This way, you can avoid having the 

configuration console going down if you for instance need to bring down a Spotfire 

Server machine for maintenance. 

For more information on the configuration console and what it does, see “Install the 

Configuration Console” on page 26. 

2.3.3 Run Installer 


Running 10.1, 3.0, or 3.1 and 3.2 on the Same Machine 

It is possible to run two versions of the server on the same machine as 

long as they communicate on different ports. 

The Spotfire Server installer will ask for three ports: Spotfire Server 

port, Configuration Console port, and Spotfire Controller port. Each of 

these applications is described in the section “Architectural Overview” 

on page 6. Ensure that you do not select any port that is already in use 

by 10.1 or 3.0. Before starting the Spotfire Server, you must also make 

sure that none of the other ports used by the servers collide. All port 

numbers are specified in the file server.xml, located in the directory 

/server/conf/ on the 10.1 server, and 

/tomcat/conf/ on the 3.0, 3.1, and 3.2 

server. For a full specification of this file, see the section “Server.xml” 

on page 135. 

Microsoft SQL Server Windows Integrated Login 

If the 3.0 or 3.1 installation authenticates with a Microsoft SQL Server 

using Windows Integrated Login, it is important to install and run the 

3.2 server using the same Windows Domain user. 

Alternatively, you can re-configure your Microsoft SQL Server to 

accept another Windows Domain user to access the Spotfire database. 

See also the section “Run the Upgrade Tool” on page 38 for 

information about the upgrade tool and Windows Integrated Login. 

In the installation kit, you will find the installer (install.exe or install.bin). Copy this 

file to the machine on which you want to install the Spotfire Server. 

It is possible to run the Spotfire Server installer silently using predefined parameters. 

This is useful when you wish to install several servers with the same setup. See 

“Installing Spotfire Server Silently Using Pre-defined Parameters” on page 84 for 

more information. 



 

Note: While it is possible for the installer to start the upgrade tool, this is not possible 

if you run the installer silently. The upgrade tool must then be run separately. 

Run the Installer: 

1 Run the installer. 

Comment: If you are using Microsoft SQL Server with Windows Integrated 

Authentication, it is important that you install the Spotfire Server with the 

same Domain User that you set up with the create_databases_ia.bat script. 

This ensures that the Domain User authenticating with the database server 

has the appropriate permissions to all files in the Spotfire Server 

installation. You must also make sure that the Spotfire Server always runs 

as this Domain User. See the section “Run Spotfire Server as Domain 

User” on page 28 for more information about this. 

2 The Introduction dialog is displayed. Click Next. 

3 The TIBCO License dialog is displayed. Read the license agreement and select the 

appropriate radio button. Click Next. 

4 The Third Party Components dialog is displayed. Select whether or not you want to 

download these. 

These components are only needed if you intend to configure your system to use 

NTLM login. If you are certain that you do not, then you can select not to download 

these. If you are unsure, it is recommended that you download these in case you later 

decide to set up your system for NTLM. If you select to download them without 

having access to the Internet, the installer will display a warning later in the 

installation process. The Spotfire products will still be installed. 

Note: These components can also be found at http://public.tibco.com/pub/tibco_oss/ 

jcifs/jcifs_1.3.14.zip. This zip file contains the file jcifs.jar. To install this file 

manually, copy it to the folder 

/tomcat/webapps/spotfire/WEB-INF/lib/. 

Click Next. 

5 If you selected to download third party components in the previous dialog, the Third 

Party License dialog is displayed. Read the license agreement and select the 


6 The Choose Install Set dialog is displayed. Select whether you want to install only the 

Spotfire Server or if you also want to install the Spotfire Configuration Console. 

If you plan to run only a single Spotfire Server, you will most likely install both the 

Spotfire Server and the Spotfire Configuration Console on the same machine. In a 

clustered environment with several Spotfire Servers, it is often preferable to install the 

configuration console on a separate machine. 

Note: If you want both on the same machine, you must install them at the same time. 

If you later decide that you want to run the configuration console on a machine which 

already has Spotfire Server installed, you must first uninstall the Spotfire Server. 



Click Next. 

7 The Installation Folder is displayed. Specify where you want to install the previously 

selected component(s). Click Next. 

8 The OS Architecture dialog is displayed. Select whether you want to install the 32-bit 

or 64-bit version of TIBCO Spotfire Server. 

The 64-bit version can only be installed on a 64-bit operating system. The 32-bit 

Windows and Solaris version can be installed on either a 64-bit or a 32-bit operating 

system. The 32-bit Red Hat and SUSE versions can only be installed on 32-bit Red 

Hat and SUSE systems. 

Note: The version of Spotfire Server you select to install must match the version of 

database drivers it uses. All JDBC database drivers packaged with the Spotfire Server 

exist in both 32-bit and 64-bit versions. If you intend to configure the Spotfire Server 

to use ODBC Data Sources (as Information Services Data Sources), please note that 

while the Spotfire Server comes bundled with a 32-bit only Oracle (Sun) JDBC- 

ODBC bridge, it is recommended that this bridge is used for testing only. For 

production use, a commercial JDBC-ODBC bridge should be used. If you intend to 

use the bundled JDBC-ODBC bridge, you must install the 32-bit version of the 

Spotfire Server. If unsure, select 32-bit. 

Click Next. 

9 Windows only. The Windows Service dialog is displayed. You have three options: 

• Do not create Windows Service. 

• Create Windows Service, but do not start it. 

• Create Windows Service, and start it at the end of installation. 

Select the option you want and click Next. 

10 The Spotfire Server Ports dialog is displayed. Specify which ports you want the 

Spotfire Server and the Spotfire controller to communicate on. Click Next. 

11 If you have selected to also install the configuration console, the Configuration Port 

dialog is displayed. Specify which port you want the configuration console to 

communicate on. Click Next. 

12 The Installation Summary dialog is displayed. Click Install. 

Response: The installation starts. 

13 The Upgrade dialog is displayed. If you are performing an upgrade from 3.0 or 3.1 to 

3.2, you can select to start the upgrade tool automatically when the installer finishes. 

Check the box if you want to do this. 

14 The Install Complete dialog is displayed. Click Done. 



Comment: A registration URL is shown in the Install complete dialog. You are 

strongly incouraged to register your Spotfire Server installation with 

TIBCO. 

If you intend to run several Spotfire Servers in a cluster, repeat these instructions for 

each machine. 

Proceed to “Install the Configuration Console” on page 26 when finished. 

2.4 Install the Configuration Console 

If you have a single Spotfire Server, then you have most likely already installed the 

configuration console at the same time you installed the Spotfire Server, that is, when 

performing the instructions in “Install Spotfire Server” on page 22. 

If you want to install the configuration console on a separate machine, then follow the 

instructions in this section. Otherwise, continue to the section “Install Patches” on 

page 29. 


Before you begin installing Spotfire Configuration Console, make sure your intended 

machine complies with the system requirements at http://support.spotfire.com/sr.asp 


The Spotfire Configuration Console is an application with a web user interface that is 

used to configure the Spotfire environment: 

• Manage the servers in a cluster. 

• Configure authentication. 

• Configure user directory. 

• Set up data source templates. 

• Configure impersonation. 

• Set up client login behavior. 

Note: If you have a single server system, it is still considered a cluster of one server. 

2.4.3 Run Installer 

In the installation kit, you will find the installer (install.exe or install.bin). Copy this 

file to the machine on which you want to install the Spotfire Configuration Console. 

Note: You cannot install the configuration console on a machine that already is 

running Spotfire Server. If you want the configuration console installed on a machine 



 

that is running Spotfire Server, you must install them at the same time. If you want to 

run the configuration console on a machine which already has Spotfire Server 

installed, you must first uninstall the Spotfire Server. 

It is possible to run the Spotfire Server installer silently using predefined parameters. 

This is useful in when you wish to install several servers with the same setup. See 

“Installing Spotfire Server Silently Using Pre-defined Parameters” on page 84 for 

more information. 

To run the Installer: 

1 Run the installer. 

2 The Introduction dialog is displayed. Click Next. 

3 The TIBCO License dialog is displayed. Read the license agreement and select the 


4 The Third Party Components dialog is displayed. You do not need these for the 

configuration console, so select not to download these. 

Click Next. 

5 The Choose Install Set dialog is displayed. Since you are installing the configuration 

console on a separate machine from the Spotfire Server, select to install only the 

Spotfire Configuration Console. 

Click Next. 

6 The Installation Folder is displayed. Specify where you want to install the previously 

selected component(s). Click Next. 

7 The OS Architecture dialog is displayed. Select whether you want to install the 32-bit 

or 64-bit version of TIBCO Spotfire Server. 


version can be installed on either a 64-bit or a 32-bit operating system. 


Windows and Solaris version can be installed on either a 64-bit or a 32-bit operating 

system. The 32-bit Red Hat and SUSE versions can only be installed on 32-bit Red 

Hat and SUSE systems. 

Click Next. 

8 Windows only. The Windows Service dialog is displayed. You have three options: 

• Do not create Windows Service. 

• Create Windows Service, but do not start it. 

• Create Windows Service, and start it at the end of installation. 

Select the option you want and click Next. 



9 The Configuration Port dialog is displayed. Specify which port you want the 

configuration console to communicate on. Click Next. 

10 The Installation Summary dialog is displayed. Click Install. 

Response: The installation starts. 

11 The Upgrade dialog is displayed. If you are performing an upgrade from 3.0 or 3.1 to 

3.2, you can select to start the upgrade tool automatically when the installer finishes. 

Check the box if you want to do this. 

12 The Install Complete dialog is displayed. Click Done. 

2.5 Run Spotfire Server as Domain User 

 

 

If your database server uses Windows Integrated Authentication, your Spotfire Server 

needs to run as a Windows Domain user that has permissions to use the Spotfire 

database. To do this, you must perform the following steps: 

Run Spotfire Server as Domain User using Windows Service 

1 Start Control Panel > Administrative Tools > Services. Find the service called 

“TIBCO Spotfire Server 3.2.2” Double-click it to open its Properties dialog. 

2 Select the tab Log On. 

3 Check the radio button This account and enter the user credentials of the Domain 

User set up with the database preparation script create_databases_ia.bat. 

4 Click OK. 

5 Restart the server. 

Run Spotfire Server as Domain User without Windows Service 

6 Log onto the Spotfire Server machine as the Domain User set up with the database 

preparation script create_databases_ia.bat. 

7 Start a command prompt. 

8 Go to the folder /tomcat/bin 

9 Run the startup.bat file. 

Response: The Spotfire Server Controller starts. 

10 The controller will stop running if you close the command prompt or log out of the 

machine. 

Note: Using Windows Integrated Authentication has security implications regarding 

the Configuration Console. See the section “Restricting Access to the Configuration 

Console” on page 89 for more information about this. 



2.6 Install Patches 

Before you continue, you must install all patches released for Spotfire Server 3.2. 

Check the URL http://support.spotfire.com/patches_spotfireserver.asp and 

download the latest collection of patches. Installation instructions for each patch are 

included in the package. 

Note: If you do not perform this step, later steps may fail. 

2.7 System Configuration 

When you have installed all applicable patches, the next step is to configure the 

Spotfire system. 

If you are migrating from 10.1, see instructions in “Migration from 10.1” on page 30 

on how to migrate your information from your 10.1 system. 

If you are upgrading from 3.0 or 3.1, see the chapter “Upgrade from 3.0 or 3.1 to 

3.2” on page 37 for instructions on how to perform such an upgrade. 

If you are installing TIBCO Spotfire Server for the first time, see the chapter 

“Configure the System” on page 47 for instructions on how to configure the Spotfire 

system. 


Migration from 10.1 

3 Migration from 10.1 


If you are migrating from Spotfire Analytics Server 10.1 to Spotfire 

Server 3.2, you must first install a 3.2 server as described in the 

previous chapters. When this is done, you can continue with the 

instructions below. 

Note: You must migrate the 10.1 information before you proceed to 

configure the system and start the server. If the Spotfire Database 

contains anything except what the database preparation scripts create, 

the migration tool will not be able to migrate the 10.1 data to it. See the 

section “Restoring a Spotfire 3.2 Database” on page 35 for more 

information about this. 

3.1 Overview 

The migration tool is an application that transfers data from a TIBCO Spotfire 

Analytics Server 10.1 database to a TIBCO Spotfire 3.2 database. It transfers the 

information stored in the database, including users (if database authentication is used), 

groups and licenses, the Library, and the information model. It does not transfer 

deployments. Its intended use is to migrate data from a 10.1 database to a 3.2 database 

in connection with a server upgrade. 

Note: The migration tool cannot be used to keep a 10.1 and a 3.2 database 

synchronized. 

The target database, that is the 3.2 database, must be prepared, using the database 

preparation scripts that are packaged with Spotfire Server. However, the database must 

be empty before you can use the migration tool. If something is already stored in the 

database the migration tool will not be able to to migrate the 10.1 data. 

Users, groups, licenses, and configuration will automatically be stored in the 3.2 

database, but the Library and the information model will be stored in export files that 

can later be imported into the 3.2 database. 

You can select whether to do a “full migration” or a “partial migration”. The latter 

only extracts the library and the information model from the 10.1 database and puts 

these items in export files. 

You can also select to do a “test run”, meaning that all steps are performed, but no 

actual data is written to the 3.2 database. Note that if you have selected “partial 

migration”, this selection has no effect, as nothing will be written to the 3.2 database in 

either case. 

You can perform as many test runs as you want, and also as many partial migrations as 

you want, but once you have performed a full migration you must empty the 3.2 

database if for some reason you need to perform a partial or full migration again. 



3.2 Prerequisites 

In order to run the migration tool, you need a functional Spotfire Analytics Server 10.1 

including database, and a prepared 3.2 database. See the section “Prepare the 

Database” on page 16 for information on how to prepare a database for Spotfire Server 

3.2. 

You must install and run the migration tool from the 10.1 server, as you will need 

access to the filesystem where the 10.1 server is installed. You must also be able to 

connect to the 3.2 database from the 10.1 server for the migration to work. 

3.3 Install the Migration Tool 

 

You must install the migration tool on the Spotfire Analytics Server 10.1, as it requires 

file system access to the 10.1 installation folder. 

To install the migration tool: 

1 Copy the migration folder of the Spotfire Server distribution, and place it on the 

Spotfire Analytics Server 10.1. 

2 Run the install.exe (or install.bin) found in this folder. 

3 Proceed through the steps of the installer wizard. When prompted for a destination 

folder, specify a folder in which to install the migration tool. 

Click Finish when the installer finishes. 

3.4 Set up Database Connection File 

In order for the migration tool to be able to communicate with the 3.2 database, you 

need to provide it with an xml file that contains connection information. Distributed 

with the migration tool are two xml files, database-mssql.xml and databaseoracle.xml. 

Select the one matching your 3.2 database type. 

1 Open the file in a text editor. 

2 Find the line that reads 

jdbc:tibcosoftwareinc:sqlserver://[hostname]:1433;DatabaseName=[database-name] 

or 

jdbc:tibcosoftwareinc:oracle://[hostname]:1521;SID=[sid] 

and change it so that it matches your database, that is enter the hostname, port and 

database name or sid. 



Note: If your database server is using Windows Integrated Authentication, make sure 

to use a database URL that reflects this. See the section “Database Connection 

Configuration” on page 138 for examples of database URLs. 

3 Find the lines that read 

[username] 

[password] 

and change then to reflect the database username and password of your Spotfire 

database. This is the username and password referred to as SERVERDB_USER and 

SERVERDB_PASSWD in the section “Prepare the Database” on page 16. 

Note: If your database server is using Windows Integrated Authentication, these 

variables are not used. You can safely leave them as they are. 

4 Save the file and exit the text editor. 

3.5 Run the Migration Tool 

The migration tool is run from a command line or shell: 

C:\tibco\tss\3.2.2\migration>migrationtool.bat 

When run without any options the application will start in GUI mode. Doing so, you 

are then presented with a window that looks like this: 



The values prompted for are the following: 

When you have entered all the information above, you can perform the migration by 

clicking the Migrate button. The output of the migration tool will be presented in the 

text field below the heading Migration Log. 

When you have performed a migration, the Library content and the information model 

will be stored on disk in export files. You can then import the content of these files to 

your 3.2 database. See the section “Importing Library Content” on page 58 for more 

information about how to do this. 

Note: It is only possible to run a full migration once. If you for some reason need to 

run it again, you must first restore the database as described in the section “Restoring a 

Spotfire 3.2 Database” on page 35. It is recommended that you first perform a test run, 

to make sure that the migration will run smoothly. 

3.5.1 Command Line Usage 

10.1 directory The installation folder of the 10.1 server, for 

example C:\TIBCO\tsas101. 

Output directory The folder where the configuration and library 

will be exported to as files. Make sure this folder 

is capable of storing all the library information. 

This could easily be several Gigabytes. 

Target database 

connection file 

Include passwords 

Type of migration 

Test run 

The path to the database connection file you have 

prepared. 

This option controls whether to include 

passwords stored in the information model. 

Note: Passwords for users are always migrated 

when full migration is selected, and are not 

affected by this option. 

Specifies whether to perform a full or a partial 

migration. A partial migration only exports the 

Library content and the information model to 

export files, while a full migration also exports 

the 10.1 database information and inserts it to the 

3.2 database. 

If this box is checked, nothing will be written to 

the 3.2 database. It is recommended to always 

begin by running a test run. 

Note: The Library and information model will 

still be exported to files. 

If you wish to run the migration tool from the command line, you can do so by 

entering the migration options as command line options to the .bat or .sh file. For 

example: 



C:\migration>migrationtool.bat -s C:\TIBCO\tsas101 -d C:\output -x 

C:\migration\database.xml -t 

The above command will perform a test run of the migration and place the Library and 

information model export files in the directory C:\output. 

For a complete list of command line arguments, run the tool with the option -h: 

C:\tibco\tss\3.2.2\migration>migrationtool.bat -h 

usage: migrationtool.bat (or migrationtool.sh) 

-d destination directory (required) 

-h help 

-n no passwords migrated 

-p partial migration (only library content and information 

model) 

-s 10.1 server base directory (required) 

-t test run (run migration without writing to the target 

database) 

-v version 

-w set up and run migration via GUI 

-x target server configuration file (database.xml) 

(required) 

3.6 Database Drivers 

The migration tool will automatically scan the 10.1 installation directory for any 

database drivers used to connect to the Spotfire database. If possible, these drivers will 

be used by the migration tool to connect to the 3.2 database. However, in some 

situations, this is not possible, such as when the 10.1 server uses a database driver not 

compatible with 3.2 (such as an old native database driver provided by Oracle). When 

this happens, the migration tool will stop with an error message saying that the 

database driver cannot be used. 

If this happens, you need to manually copy a compatible database driver from the 3.2 

server to the directory /lib or download 

new drivers from the database server manufaturer. The 3.2 database drivers are located 

in the directory /tomcat/lib on the 3.2 server. 

Any database drivers used to connect to the Spotfire database or to any information 

sources set up in the 10.1 server will also be reported by the migration tool in the log 

area or on standard output. Note that if you have any special database drivers set up in 

the 10.1 server (to connect to an information source, for example), you need to 

manually copy these drivers to the 3.2 server, or acquire new ones from your database 

provider. Database drivers used to connect to the Spotfire Database (such as 

ojdbc6.jar, jtds.jar, and sqljdbc(4).jar) should be placed int the directory /tomcat/lib, and database drivers used to connect to other 

databases should be placed in the directory /tomcat/ 

webapps/spotfire/WEB-INF/lib. 

Note: If you copy database drivers from a 10.1 server, only copy the ones needed. Do 

not copy any other files from the 10.1 installation. 



3.7 Log Files 

In the migration tool installation directory, there is a folder called logs. This folder 

contains three different log files: 

debug.log 

sql.log 

warn.log 

Debug.log holds verbose information about exactly what happened, step by step, in the 

migration process. Sql.log holds information about every SQL command that was 

executed during the migration. Warn.log contains any warnings received during 

migration. 

If something goes wrong during the migration, these files may contain important 

information about the source of the problem. Do not delete them until you know that 

the migration is successful. 

3.8 Restoring a Spotfire 3.2 Database 

If the migration fails for some reason and you need to perform it again, you need to 

restore the Spotfire 3.2 database before you can do this. Distributed with the Spotfire 

Server are scripts that will do this, located in the folder scripts/mssql_install/utilities 

and scripts/oracle_install/utilities. Select the folder appropriate for your database type. 

In the Microsoft SQL folder, you will find the scripts restore_databases.bat and 

restore_databases_ia.bat. In the Oracle folder, you fill find the scripts 

restore_databases.bat and restore_databases.sh. Select the one appropriate for your 

platform and database configuration. Before you run it, you must open it in a text 

editor and edit a number of variables. Find the lines that contains the following text: 

Microsoft SQL Server 

CONNECTIDENTIFIER=\ 

SERVERDB_NAME= 

SERVERDB_USER= 

SERVERDB_PASSWORD= 

Note: If you use Windows Integrated Authentication, the variables SERVERDB_USER and 

SERVERDB_USER will not be persent. 

Oracle 

CONNECTIDENTIFIER= 

SERVERDB_USER= 

SERVERDB_PASSWORD= 

Replace these values with the information valid for your database server. See the 

section “Prepare the Database” on page 16 for more information about this 

information. 

When you have entered the information required, you can run the scripts from a 

command prompt. 



3.9 Configuration Not Migrated 

Single-sign on authentication and database authentication configuration from a 10.1 

server is compatible with a 3.2 system. If you use any such authentication, any 

configuration files, such as spotfire.keytab, krb5.conf, etc., are put in a subfolder of 

the export folder, java-mods. You need to manually move these files to the 3.2 

server(s). Refer to the chapter “Authentication and User Directory” on page 65 for 

details on where to put these files, or how to set up authentication again. 

Database drivers are not migrated and need to be copied manually from a 10.1 

installation or aquired anew from your database vendor. In the 10.1 installation, these 

drivers are located in the folder 

/server/webapps/spotfire/WEB-INF/lib. 

Copy the drivers used to connect to the Spotfire Database to 

/tomcat/lib 

Copy the drivers used to connect to other data sources to 

/tomcat/webapps/spotfire/WEB-INF/lib 

Note: Do not copy any other files from the 10.1 installation directory. If you copy all 

the files in the lib folder, for instance, the 3.2 server will be incapacitated and a reinstall 

is necessary. If at all unsure, aquire new drivers from your database vendor. 

3.10 Uninstall the Migration Tool 

When you have made sure that everything has been migrated correctly and as 

expected, you can safely uninstall the migration tool. An uninstaller created during 

install will be located in the folder /installer/. 

Once you have migrated the 10.1 data, you are ready to configure your 3.2 system. 

Please proceed to “Configure the System” on page 47. 


Upgrade from 3.0 or 3.1 to 3.2 

4 Upgrade from 3.0 or 3.1 to 3.2 

UPGRADING FROM 3.0 OR 3.1 TO 3.2? 

If you are upgrading from Spotfire Server 3.0 or 3.1 to Spotfire Server 

3.2, you must first install a 3.2 server as described in the previous 

chapters. 

Important: Do not run the database preparation scripts. 

When this is done, you can continue with the instructions below. 

4.1 Overview 

In the Spotfire Server 3.2 installation kit there is an upgrade tool. This upgrade tool 

modifies an existing 3.0 or 3.1 database and transfers configuration from a 3.0 or 3.1 

server installation to a 3.2 installation. Alternatively, it can transfer configuration from 

an already working 3.2 server installation. This is useful if you are upgrading several 

Spotfire Servers in a cluster. 

It is important to back up or clone the 3.0 or 3.1 database before you continue. Below 

are explanations to each of the two approaches mentioned above. 

4.2 Back up or Clone the 3.0 or 3.1 Database 

Before upgrading your 3.0 or 3.1 database and software installation, it is important that 

you back up or clone your existing 3.0 or 3.1 database. A “clone” means that you 

make a copy of your entire database, with all its information, into a new database, with 

a new user and password. You can run the upgrade on either the 3.0 or 3.1 database 

that you have used in production, or on a clone that you set up. There are advantages 

and disadvantages to both approaches. 

Upgrading a Production 3.0 or 3.1 Database 

In this scenario, you will upgrade the database you have been using for Spotfire 3.0 or 

3.1. The advantages of this approach are: 

• All configuration will be exactly the same. Database name and ports can be 

reused in the 3.2 installation. 

The disadvantages of this approach are: 

• You will have to stop using Spotfire 3.0 or 3.1 before you start the upgrade and 

no Spotfire system will be accessible until you have finished the upgrade. 

Cloning a 3.0 or 3.1 Database 

In this scenario, you will clone a 3.0 or 3.1 database, i.e. create an identical copy of it, 

and perform the upgrade the clone. The advantages of this approach are: 



• You will be able to run the Spotfire 3.0 or 3.1 system while you upgrade. 

• If something should go wrong during the upgrade, your users will not be 

affected by this and can continue running Spotfire 3.0 or 3.1. 

The disadvantages of this approach are: 

• Spotfire client configuration will have to change, either because you install 

Spotfire Server on a new machine, or on the same machine as 3.0 or 3.1, but 

listening to a different port. 

• If users continue using the 3.0 or 3.1 system during upgrade, you will have to 

export content from the 3.0 or 3.1 database and import it to the 3.2 database 

before the users make the switch to 3.2. 

The upgrade tool will ask you which of the scenarios you want to perform. Depending 

on how you answer, the tool will behave slightly differently. 

If you are running a fairly simple system, with only one or a couple of Spotfire 

Servers, and downtime during upgrade is acceptable, you should probably upgrade the 

production 3.0 or 3.1 database. 

4.3 Run the Upgrade Tool 

HAVE YOU BACKED UP OR CLONED YOUR 3.0 or 3.1 DATABASE? 

Before you run the upgrade tool, it is very important that you make sure 

you have a working backup or a clone of your 3.0 or 3.1 database. 

In the Spotfire Server installation directory, there is a subdirectory called upgrade. 

There you can find the files upgradetool.bat (Windows) and upgradetool.sh (Unix). 

Double-click on the file appropriate for your operating system. You can also start it 

from a command line or a shell prompt if desired. The typical and recommended way 

to start it is to have the Spotfire Server Installer start it. 

Note: If you have installed Spotfire Server on Windows and selected to create a 

Windows Service and to start it after the installation is done, and then select to run the 

upgrade tool, the Windows Service will start after the upgrade tool has finished. 

The upgrade tool consists of a number of screens which will prompt you for 

information regarding your 3.0 or 3.1 installation and your 3.2 installation. Depending 

on selections you make on one screen, the following screens may look slightly 

different. 

If you need to quit the upgrade tool for some reason, you can select to “Save and 

Quit”, and the upgrade tool will continue from where you left off the next time you 

start it. 



Below is a description of each screen in the upgrade tool. 

ARE YOU USING MICROSOFT SQL SERVER WITH WINDOWS INTEGRATED 

LOGIN? 

Welcome Screen 

If Spotfire Server is set up to authenticate with the Spotfire database 

using Windows Integrated Authentication, it is important that you run 

the upgrade tool as the same user that Spotfire Server authenticates as. 

Otherwise, the upgrade tool will not be able to authenticate with the 

database. 

Alternatively, you can clone the 3.0 or 3.1 database and allow a 

different Windows Domain user to access it. 

Note: Windows Integrated Authentication implies that the same login 

is always used when authenticating. If the Spotfire Server connects to 

the Spotfire database using Integrated Authentication, and also 

connects to other databases (information sources) authentication with 

all databases will be performed using the same Windows login. 

The first screen will remind you again to perform a backup. Select Next to continue. 



File Locations 

This screen asks you from where you wish to copy configuration. You can copy 

configuration either from a 3.0 or 3.1 installation or from a 3.2 installation. The latter 

is useful if you are upgrading several servers in a cluster and you have already 

upgraded one or more servers. 

If you select to not copy configuration, you will have to enter all configuration 

manually on following screens. 



Database Upgrade 

This screen asks you if you are upgrading a production 3.0 or 3.1 database or if you are 

upgrading a clone of the 3.0 or 3.1 database. Depending on how you reply, the 

following screens may look different. 

If you selected not to copy configuration, you will not see this screen. 

Database Drivers Not Installed 



This screen informs you that the upgrade tool cannot find a suitable database driver to 

connect to the database. This should only happen if you are using old native database 

drivers not supported by Spotfire Server 3.2 and the upgrade tool. You must manually 

copy this database driver from a working Spotfire Server installation to the /tomcat/lib directory. See the section “Database Connection 

Configuration” on page 138 for more information about database drivers. When you 

click Done, the upgrade tool will exit. The next time it starts, it will remember the 

selections you made on the screen before this. 

If there are no database drivers issues, you will not see this screen. 

Database Type and Driver 

This screen asks you what type of database and what database connection type (driver) 

you are using to connect to the database that will be upgraded. 

If you selected to copy an existing configuration, you will not see this screen. 



Database Connection Information 

This screen asks you for the connection string, username, and password to the 

database that will be upgraded. 

If you selected to copy configuration and to upgrade a production database, the 

information on this screen will be filled out for you. If you selected to copy 

configuration but to upgrade a cloned version of the database, the 3.0 or 3.1 production 

database connection string will be printed out on the screen, but you will have to 

manually enter the connection string of the cloned database. 



Server Information 

This screen asks you if you want to remove all servers from the cluster, and if you 

want to add the computer you are running the upgrade on to the cluster. If this is the 

first (or the only) server in the cluster you are upgrading, you should remove all 

servers from the cluster. 

Click Upgrade to perform the upgrade. 

If you have already upgraded one server in the cluster, the upgrade will not make any 

changes to the database, as it is was upgraded the first time you ran the upgrade tool. 

In this case, the upgrade tool will update configuration to the software installation on 

the computer you are running, either by copying it from a 3.0, 3.1, or 3.2 installation, 

or from the information you entered in the upgrade tool. 



Upgrade 

This screen will show after the upgrade is finished. It also has information about how 

the upgrade went. Following a successful upgrade, it should read either “The database 

has been upgraded to TIBCO Spotfire Server 3.2 format” or “The database has already 

been upgraded to TIBCO Spotfire 3.2 format”, the latter indicating that the database 

was already in the 3.2 format. 

Upgrade Issues 



This screen will list any issues that occurred during upgrade. These might include port 

conflicts, missing database drivers, or any other issues discovered during upgrade. 

Please take notice of all the issues, if any. You may have to correct some or all of them 

manually, either by copying files to the right location, or by configuring the Spotfire 

system using the Configuration Console. 

This screen will only appear if there are any issues that need to be addressed. 

4.4 Default Join Database 

If you have set a default join database in your 3.0 or 3.1 installation to be the Spotfire 

database, and also upgraded a clone of the 3.0 or 3.1 database to 3.2, you will need to 

reset the default join database as it will still be set to the 3.0 or 3.1 database. Log into 

the Configuration Console, select the Default Join Database tab, and change the value 

to the 3.2 database. 

If you have not set a default join database, or set it to a different database than the 

Spotfire database, you can ignore this step. 

4.5 Start the Spotfire Server 

When the upgrade tool has completed and you have verified that there are no issues 

with the upgrade, you need to start the Spotfire Server. See the section “Starting and 

Stopping the Spotfire Server” on page 104 for instructions on how to do this. 

4.6 Verify Configuration 

When you have started the Spotfire Server, you should log into the Configuration 

Console and verify that all configuration is as it was before the upgrade. If you need to 

make any changes, please refer to the next chapter, “Configure the System” on 

page 47. 


Configure the System 

5 Configure the System 

5.1 Overview 

After you have set up a database and installed the server software, you must perform a 

number of steps to get the system up and running. This chapter will guide you through 

the different steps you need to perform. 

5.2 Spotfire System Security 

You may wish to configure security in the Spotfire system. 

There are several (manual) measures that may be taken. The options available and 

recommended are totally depending on the the environment in which the Spotfire 

system is installed. You should confer with network managers and the like to come up 

with a solution that fits your specific environment. 

The different measures you can take include: 

• Set up Spotfire to communicate using HTTPS. See the section “Setting up 

HTTPS on a Spotfire Server” on page 86 and/or “Setting up HTTPS in a Load 

Balanced Environment” on page 97 for more information about this. 

• Using X.509 client certificates to authenticate users. See the section “Creating 

and Installing a Self-Signed Client Certificate” on page 95 for more information 

about this. 

• Setting up LDAP authentication over SSL. See the section “Configuring 

LDAPS” on page 91 for more information about this. 

• Configuring the Spotfire Server(s) to authenticate with the database using 

Kerberos. See the section “Database Authentication using Kerberos” on page 91 

for more information about this. 

• Restricting access to the configuration console. See the section “Restricting 

Access to the Configuration Console” on page 89 for more information about 

this. 

Note: For optimal security some of these measure should be taken before you set up 

basic configuration. If you think any of these measures apply to you, then it is 

recommended that you read the corresponding instructions before you proceed below. 

5.3 Database Drivers 

Spotfire Server ships with DataDirect database drivers. While these drivers work well 

for test environments and for running the database preparation scripts as described 

above, it is strongly recommended that drivers native to your database server are used 

in a production environment. Native drivers (JDBC) are available from your database 



server manufacturer. If they are drivers used to connect to the Spotfire database 

(typically ojdbc6.jar, jtds.jar, or sqljdbc(4).jar), place them in the directory 

/tomcat/lib 

If they are drivers used to connect to other databases (information sources), place them 

in the directory 

/tomcat/webapps/spotfire/WEB-INF/lib 

When you have installed the database drivers, the Spotfire Server needs to be restarted 

according to the instructions in the section “Starting and Stopping the Spotfire Server” 

on page 104. 

Note: The database connection URL, used by the server to connect to the database, 

may be different for different database drivers. See the section “Database Connection 

Configuration” on page 138 for a comprehensive description of the database 

connection URL, and for examples using different database drivers. 

Data Sources in the Information Designer 

The Information Designer tool, available in the Spotfire client, allows users to create 

analyses based on external data sources. These external data sources are accessed 

using database drivers. Any database drivers you install in the folders listed above are 

available for use in the Information Designer. 

To connect to an external data source, you also need to enable a data source template 

that matches the data source and a specific database driver. This is done in the 

configuration console. Detailed information about how to do this can be found in the 

configuration console help. 

5.4 Starting the Spotfire Server Controller 

Before proceeding, you must start the Spotfire Server controller. This is the small 

application that is used to start and stop the actual Spotfire Server. 

5.4.1 For Windows, with Windows Service 

If you selected to install a Windows service, and automatically start it at the end of the 

installation (see step 9 on page 25), then the Spotfire Server Controller is already 

running. The name of the service is “TIBCO Spotfire Server 3.2.2”. 

If you selected to install a Windows service, but not to start it at the end of the 

installation (see step 9 on page 25), then you must now start the service manually. Start 

Control Panel > Administrative Tools > Services. Find the service called “TIBCO 

Spotfire Server 3.2.2” and start it. 

Note: If you for some reason need to reinstall the Windows Service after installation, 

run the bat file /tomcat/bin/service.bat with the argument 

install: 

/tomcat/bin/service.bat install 



You can also run this script with the argument remove to remove the Windows 

Service. 

/tomcat/bin/service.bat remove 

5.4.2 For Windows, with No Service 

If you selected not to install a Windows service (see step 9 on page 25) then you must 

start the Spotfire Server manually. 

1 Log onto the Spotfire Server machine as an administrator. 





Comment: The controller will stop running if you close the command prompt or log 

out of the machine. 

5.4.3 For Solaris, Red Hat, and SUSE 

 

To start Spotfire Server on reboot: 

After the installation, you may want to configure Spotfire Server to start automatically 

each time the Solaris, Red Hat, or SUSE machine is rebooted. This can be set up by 

running a script called install_startup_script.sh. 

1 Log in as root. 

Comment: In order to have a service automatically start at reboot you must be root. 

No other user can do this. 

2 Navigate to the /tomcat. 

3 Execute the file install_startup_script.sh. 

Response: The Spotfire Server will start automatically after each machine reboot. 

To start the server right now, run the script 

/etc/init.d/tss start 

Note: The install_startup_script.sh script copies the script tss, also located in 

/tomcat, to the /etc/init.d directory and places symbolic 

links to this scripts in the appropriate runlevel directories (/etc/rc2.d etc). 

 

To start Spotfire Server in a terminal: 



If you wish to run Spotfire Server in a terminal, then execute the command startup.sh 

located in the directory /tomcat/bin with the same user as 

the one who installed the Spotfire Server. 


5.5 Starting the Configuration Console 

If you have installed everything correctly, you will reach the configuration console by 

entering the URL 

http://hostname:/config (where hostname is the hostname of the machine 

running the configuration console and port the port the configuration control is 

listening to, by default 8080) into a web browser (see the chapter “Install the 

Configuration Console” on page 26 for details on how to install the configuration 

console). 

Note: If you are using Internet Explorer running on Windows Vista or Windows 2003 

or later with Windows Enhanced Security is enabled, you must add the configuration 

console URL to the list of “Trusted sites”, on the Security tab of the Internet Options. 

If you do not do this, the configuration console will fail to load. 

When you start the configuration console for the first time, the following things will 

happen: 

1 The configuration console will detect that there is no database defined to verify the 

login information with. You will be presented with a dialog where you must enter a 

valid database URL before you can continue. You can select database server type and 

driver from a dropdown menu, which will provide you with the URL syntax. For 

instance 

jdbc:tibcosoftwareinc:sqlserver://[DBServer]:[DBServerPort];DatabaseName=[DatabaseName] 

or 

jdbc:tibcosoftwareinc:oracle://[DBServer]:[DBServerPort];SID=[DatabaseSID] 

using DataDirect drivers. DBServer should be replaced with the fully qualified 

hostname (that is, including the domain name) of your database server, port with the 

port the server is listening to, and databasename with the name (or sid) of your 

database. For example, if you are using a standard MSSQL server called 

dbsrv.company.com, listening to port 1433, and you have not changed the default 

name of the Spotfire database, the URL should read: 

jdbc:tibcosoftwareinc:sqlserver://dbsrv.company.com:1433;DatabaseName=spotfire_server 

If you are using Microsoft SQL Server with Integrated Authentication, the URL 

should look like this: 

jdbc:tibcosoftwareinc:sqlserver:// 

dbsrv.company.com:1433;DatabaseName=spotfire_server;AuthenticationMethod=ntl 

m;LoadLibraryPath=c:/tibco/tss/3.2.2/tomcat/lib 



Note: This information cannot be entered into the configuration console after this has 

been started and connected to the database. If you need to change it later, for instance, 

if you move your database server, please refer to the section “Database Connection 

Configuration” on page 138. This section also contains more examples of connection 

URLs. 

Also note that it is possible to use another driver to access your database. Spotfire 

Server supports DataDirect (tibcosoftwareinc) by default. See the section “Database 

Drivers” on page 47 for a brief description on what other database drivers you can use. 

2 The configuration console will prompt for username and password. This information 

is identical to the username and password created for the database, described in the 

section “Prepare the Database” on page 16. 

Comment: If you are using Microsoft SQL Server with Integrated Authentication, this 

dialog will still show. Click OK without entering any information in the 

username and password boxes. 

3 After your login information has been verified with the database, the configuration 

console will detect that no cluster has been defined. You must set up a new cluster 

before you can continue. Note that even if you only have one Spotfire Server in your 

Spotfire system, this server will be part of a cluster of one server. 

4 The configuration console will ask you if you want to import a configuration file. This 

is useful if you have previously exported configuration console settings to a file, for 

instance if you are re-installing a Spotfire system. 

After you have completed these preliminary tasks, the configuration console is ready 

to configure your Spotfire system. Basic configuration tasks include setup of 

authentication and user directory methods, and the adding of Spotfire Servers to the 

cluster. 

If you attempt to log into the configuration console and the administrative user is 

already logged in, you will be asked if you wish to terminate the other login and 

proceed with the current one. Use this with care, especially if there are more than one 

administrator of the Spotfire system. 

5.6 Setting up Authentication 

Authentication is the verification of user login information. This information usually 

consists of username and password, and is by default stored in the Spotfire database. 

You can also configure Spotfire to authenticate users with an existing LDAP server in 

your network, such as a Windows Active Directory Server, a Windows NT4 Domain 

Controller, or the NTLM protocol. 

All of these settings are set in the configuration console, and regardless of which 

method you select, the users are always presented with the same login screen when 

starting a Spotfire client, unless you configure the system to use a single sign-on 

method, such as Kerberos or X.509 Client Certificate. For more details on these 

choices and recommendation about which to use, please see the section 



“Authentication and User Directory” on page 65. 

 


When you start the Spotfire Configuration Console and connect to the 

3.2 database you should verify that the configuration from the Spotfire 

Analytics Server 10.1 has been transferred correctly. 

Configuring Authentication: 

1 In the configuration console, click on the tab Authentication. 

2 Click the Edit button. 

Most login/user directory configurations will have transferred 

completely and will not require any additional setup. However: 

• If you have set up external LDAP group synchronization, the list 

of groups specified for synchronization will be transferred to the 

3.2 server. However, you must enable group synchronization and 

set up synchronization schedules for the groups from the 

configuration console. 

• Kerberos, X.509 Client Certificates, and NTLM authentication 

information is not transferred. If you intend to use any of these 

authentication methods on the 3.2 server, you need to set this up 

again. 

3 If prompted to stop all servers, select to do so. 

4 Select the login method you wish to use from the Login method drop-down menu. 

5 Depending on your choice you will be presented with a number of additional 

parameters that you must specify. 

For more details on these parameters, please see the configuration console online help 

by clicking on the question mark icon in the top right corner. 

6 Click the Done button when you are finished. 

5.7 Setting up User Directory 

The user directory is where the Spotfire system stores user names and group 

memberships. This information can later be used to set permissions to different groups 

of users. The user directory is stored in the Spotfire database, but to simplify 

administration, it is possible to import this information from an external source, such 

as an LDAP directory. This is called User Directory Back-end. For a comprehensive 

list of user directory backends, and how they can be combined with different 

Authentication methods, see the section “Authentication and User Directory” on 

page 65. 

 

Configuring User Directory: 



1 In the configuration console, click on the tab User Directory. 

2 Click the Edit button. 

3 If prompted to stop all servers, select to do so. 

4 Select the user directory back-end you wish to use from the User directory back-end 

drop-down menu. 

5 Depending on your choice you will be presented with a number of additional 

parameters that you must specify. 

For more details on these parameters, please see the configuration console online help 

by clicking on the question mark icon in the top right corner. 

6 Click the Done button when you are finished. 

Note that the settings made here do not include moving users between groups or 

creating new groups, only from where to fetch user directory information, whether it 

be from the Spotfire database or from an external source. 

5.8 Add Server to Cluster 

In order for users to be able to use Spotfire, you need to add at least one Spotfire 

Server to the cluster you set up on first login to the configuration console. 

In the configuration console, click on the tab “Cluster Servers” to add servers to your 

cluster. Then click on the green + sign in the list of servers and you will be prompted 

to specify: 

• Server protocol (http or https) 

• Server hostname or IP address 

• Spotfire Controller port (default 8078) 

• Spotfire Server port (default 80) 

Make sure to select either HTTP or HTTPS in the dropdown menu, according to what 

protocol you have set up the Spotfire Controllers to use. (Do not type http or https into 

the text field for server hostname, only type the actual hostname or IP address). 

You will also be prompted about uploading a database.xml file to the server. This is the 

server configuration file in which the database connection URL is stored. 

Note: If you select to not upload this file, you will have to copy it manually to the 

/tomcat/webapps/META-INF directory on the server before 

you can start the server. 



5.9 Start All Servers 

After you have performed all the above tasks, you are ready to start your cluster. In the 

configuration console, there is a button that says Start All Servers. You can also start 

or stop individual servers belonging to the cluster. 

When the Cluster Status Indicator turns green to indicate that at least one server in the 

cluster is up and running, you are ready to proceed. 

5.10 Setting up Shared Disk Location 

Files that are to be imported into the Spotfire Library by Spotfire Admins need to be 

placed in a specific directory in order to be imported. You specify this folder in the 

Shared Disk Location setting, found in the Cluster Servers tab of the Spotfire 

Configuration Console. By default this is /tomcat/ 

application-data/library. For most intents and purposes, this setting does not need 

to be changed. 

Please see the online help for the configuration console for detailed information on 

how to use the configuration console. 

5.11 Making the Demo Database Available 

If you installed the demo database during install, there is one more step you need to 

perform in order to make the demo database available to users. 

In the Spotfire Server installation media, there is a folder called demodata. Select one 

of its subfolders, oracle or mssql depending on your database server, and copy the file 

within this folder, demo.part0.zip to the shared disk location discussed in the previous 

section. This zip file contains analysis files and an information model that links to the 

demo data. 

When this file is in place, a Spotfire Admin or a Library Admin can import these files 

to the Library. 

5.12 Assign Admin User 

When the Spotfire cluster is up and running, you need to assign administrator 

privileges to a Spotfire user. Spotfire administration includes tasks such as creating 

users, managing licenses, and deploying packages. If you are using Database 

Authentication, you must first create an initial Spotfire user, and then assign 

administrator privileges to this user. If you are using external authentication, such as 

an LDAP Directory, you need to assign administrator privileges to one of these users. 

In the configuration console, click on the tab “Assign Admin User”. If you are using 

Database Authentication, first create an initial Spotfire user by clicking the button 

“Create User”. Then click the button “Assign Privileges” to assign administrator 



privileges to a Spotfire user. Note that you have to supply the username and password 

for the user that you assign administrator privileges to. 

When you do this, you need an unlock code found in the file codes.txt in the 

documentation folder in the Spotfire Server distribution. Note that this unlock code 

can be used only once. 

Once the first admin user is assigned, this user may assign administrator privileges to 

other Spotfire users. 

Once the Spotfire system is installed and configured, and a Spotfire Admin is 

assigned, the system is ready to be administered. Before users can start using the 

system, there are a number of administrative tasks that need to be performed. These 

tasks are described in the chapter “Spotfire Administrative Tasks” on page 56. 


Spotfire Administrative Tasks 

6 Spotfire Administrative Tasks 

6.1 Overview 

When the Spotfire Server has been installed, there are some additional tasks that must 

be performed in order for users to be able to use the Spotfire clients. These tasks are 

referred to as Spotfire administrative tasks, and are usually performed by a Spotfire 

Administrator. 

TIBCO Spotfire Deployment is a software distribution needed to deploy and 

administer Spotfire. It is a separate distribution and it is found on the TIBCO Spotfire 

software download web site. In this distribution the TIBCO Spotfire - Deployment 

and Administration Manual is found. This manual describes the Spotfire 

administrative tasks. Below is a brief outline of the tasks that need to be done before 

the Spotfire system can be used, and the tools involved in performing these tasks. 

If these steps are not performed, users will not be able to use Spotfire. Refer to the 

TIBCO Spotfire - Deployment and Administration Manual for detailed 

instructions on how to perform these steps. 

6.2 TIBCO Spotfire Administration Tools 

To perform Spotfire Administrative tasks, there are three different tools available. 

These tools perform different tasks, and it is important that a Spotfire Admin is 

familiar with all of them. 

6.2.1 TIBCO Spotfire Administration Console 

Each TIBCO Spotfire Server has a web-based administration UI called the TIBCO 

Spotfire Administration Console. This tool is used to set up users and groups (unless 

users and groups are handled by an external mechanism such as an LDAP server), and 

to deploy Spotfire packages.. It can be reached by a standard web browser using the 

URL http://spotfireserver/spotfire/administration/, where spotfireserver is 

the hostname of one of your Spotfire Servers. If you are not running Spotfire Server on 

the standard port 80, you must also add the port number in the URL: http:// 

spotfireserver:8080/spotfire/administration/ It does not matter which server in 

the cluster you use, changes made to one server will be stored in the Spotfire database 

and available to all servers. 

For detailed help on how to use the Administration Console, please see its online help. 

6.2.2 TIBCO Spotfire Administration Manager 

In the Spotfire client, there is an administration tool called the Administration 

Manager. This tool is used to set up licenses and preferences. It is also possible to 

create new users and groups in this tool. It is found on the Tools menu in the Spotfire 

client. 



6.2.3 TIBCO Spotfire Library Administration 

In the Spotfire client, there is also an administration tool called the Library 

Administration. This tool is used to administer the Spotfire Library. The Library is a 

feature that allows Spotfire users to publish and share analyses and data with each 

other. 

The content of the Library can be exported and imported. This can be used as a backup 

function. If you have migrated from Spotfire Analytics Server 10.1, the Migration 

Tool has exported the 10.1 Library content. To import it, see the section “Importing 

Library Content” on page 58. 

6.3 Deploying TIBCO Spotfire 

A Spotfire deployment consists of software packages and licenses packaged into 

distributions and uploaded to and stored in the Spotfire database. For a user to be able 

to log in, and for Spotfire clients to work properly, a Spotfire deployment must be 

present at login time. Software patches and license information stored in the 

deployment will be downloaded to and control the behavior of the clients. 

A Spotfire deployment is created by obtaining the TIBCO Spotfire Deployment 

distribution and upload it to the Spotfire server using the Administration Console. See 

its help for more information about this. 

6.4 Setting up Users, Groups, and Licenses 

Spotfire licenses control which software features are available to different users. 

Licenses are set for groups. If you are using an external mechanism to handle users 

and groups, you can create Spotfire groups and put the external groups into the 

Spotfire groups. Users and groups can be created and deleted in the Administration 

Console. Licenses are set in the Administration Manager, on the tab Groups and 

Licenses. See each tool’s help for detailed information and help on setting up Users, 

Groups, and Licenses. 



6.5 Importing Library Content 


The Migration Tool exported the 10.1 Library content to Library export 

files ready for import into the 3.2 Library. 

Note: The 10.1 library allowed for case sensitive item names if it was 

stored in an Oracle database. This meant that you could have two 

folders, one named “folder” and another named “Folder” on the same 

level of the library file tree. Version 3.0 and later treats Library item 

names as case insensitive, regardless of whether the library is stored in 

an Oracle or a Microsoft SQL Server database. Therefore, when you 

import a 10.1 library that was stored in an Oracle database, you must 

select to automatically change any such conflicting names by checking 

the option “Automatically assign new name or GUID to imported item” 

in the import dialog. 

Importing Library content is performed by using the Library Administration Tool. The 

TIBCO Spotfire - Deployment and Administration Manual and the online help of 

the Library Administration tool have detailed information on how to do this. 

When the TIBCO Spotfire Server was installed, there was an option of populating the 

database with demo data. Also packaged with the TIBCO Spotfire Server is a collection 

of Spotfire analysis files and an information model that links to this data. If the 

demo data is installed in the database, you can import these demo files into the library. 

Using the demo files is a good way to learn how to use Spotfire. See the TIBCO Spotfire 

- Deployment and Administration Manual for more information and detailed 

instructions on how to import the demo files. 


Load Balancing 

7 Load Balancing 

This chapter explains the concept of load balancing in a clustered environment, and 

how to set this up if you are running multiple Spotfire Servers in a cluster. 

7.1 Overview 

Load balancing is a technique for spreading the workload between two or more 

computers. 

In a clustered environment, each Spotfire client connects to a single network host, a 

load balancer, which redirects calls to an available Spotfire Server. It is important that 

the load balancer is able to redirect follow-up connections from the client to the same 

Spotfire Server for the duration of the user session (session affinity). It must also be 

able to detect when a Spotfire Server is unavailable, such as when maintenance is 

being performed, and stop directing traffic to that server. When the Spotfire Server 

becomes available again, the load balancer must start directing calls to it again. If you 

wish to implement your own load balancing solution, these requirements must be met, 

with special emphasis on session affinity, without which communication between 

clients and servers will not work. 

The rest of this chapter assumes that you are using a load balancing solution based on 

Apache httpd with the mod_jk module enabled. Because the Spotfire Server is 

implemented as a Tomcat Service, and therefore supports the AJP (Apache JServ 

Protocol) protocol, this technology provides a good starting point for achieving a load 

balanced Spotfire system. 

To set up load balancing, configuration needs to be done on all the cluster nodes, as 

well as on the load balancer itself. 

7.2 Prerequisites 

• At least two Spotfire Servers need to be installed and configured. 

• Apache httpd and the mod_jk module need to be installed on the load balancer. 

• Optional: If NTLM authentication is used, the mod_auth_sspi module needs to 

be enabled in Apache httpd. 

7.3 Cluster Node Configuration 

Each Spotfire Server is prepared for communication with a load balancer on 

installation. You do not need to change anything on the servers. If you are well 

acquainted with load balancing and want to change any default settings, they are all set 

in the file server.xml. See the section “Server.xml” on page 135 for more information 

about this file. 



7.4 Load Balancer Configuration 

The load balancer needs to be configured so that it will be able to find and 

communicate with the Spotfire Servers. 

1 Install Apache httpd. 

2 Install the mod_jk module. Refer to the Apache httpd manual for instructions on how 

to do this. 

3 Add the following to workers.properties (you may need to create this file): 

# Define worker list 

# (All workers with additional exposed applications must also be added here, 

# and don't forget to add the corresponding JkMount option in mod_jk.conf!) 

worker.list=jkstatus, loadbalancer 

# Example: the /admin application on worker1 should be exposed through the load balancer 

#worker.list=jkstatus, loadbalancer, worker1 

# Set status 

worker.jkstatus.type=status 

# Set properties for the load balancer 

worker.loadbalancer.type=lb 

worker.loadbalancer.balance_workers=worker1, worker2 

worker.loadbalancer.sticky_session=true 

worker.loadbalancer.method=Session 

# Set properties for worker1 (ajp13) 

worker.worker1.type=ajp13 

worker.worker1.host=[SpotfireServer1Hostname] 

worker.worker1.port=8009 

worker.worker1.max_packet_size=65536 

worker.worker1.lbfactor=1 

worker.worker1.route=[SpotfireServer1Hostname]-srv 

# Set properties for worker2 (ajp13) 

worker.worker2.type=ajp13 

worker.worker2.host=[SpotfireServer2Hostname] 

worker.worker2.port=8009 

worker.worker2.max_packet_size=65536 

worker.worker2.lbfactor=1 

worker.worker2.route=[SpotfireServer2Hostname]-srv 

Change [SpotfireServer1Hostname] to the hostname or IP address of your first 

Spotfire Server, [SpotfireServer2Hostname] to the name of your second Spotfire 

Server, and so forth. 

Note: The AJP route is automatically set to “[SpotfireServerHostname]-srv” on the 

Spotfire Server end at installation, that is the hostname of the server suffixed by “- 

srv”. 

4 Add the following to the mod_jk.conf file (you may need to create this file): 



# Load the mod_jk module 

LoadModule jk_module modules/mod_jk.so 

# Load the workers configuration 

JkWorkersFile conf/workers.properties 

# The mod_jk module's log file 

JkLogFile logs/mod_jk.log 

# The mod_jk module's log level (trace, debug, info, warn, error) 

JkLogLevel info 

# Let the load balancer worker handle all requests to the TSS web applications 

JkMount /spotfire loadbalancer 

JkMount /spotfire/* loadbalancer 

# Define Apache environment variables to be exported by mod_jk to Tomcat web 

applications 

JkEnvVar REMOTE_USER 

JkEnvVar SSL_CLIENT_CERT 

#JkEnvVar SSL_CLIENT_CERT_CHAIN 

#JkEnvVar SSL_CLIENT_S_DN 

#JkEnvVar SSL_CLIENT_S_DN_CN 

5 Make sure that the Apache httpd configuration includes the file mod_jk.conf. 

6 Restart Apache httpd. Check for any startup errors. 

7 Make sure you are able to connect to each server using both HTTP on the ports 

defined in the installation process, and using AJP on port 8009. 

8 To achieve a higher level of security, it is possible to make the load balancer 

authenticate when it talks to the Spotfire servers. See the section “Load Balancer AJP 

Keyword Restriction” on page 63 for more information about this. 

Note: It might be a good idea to start by setting up one Spotfire Server to be load 

balanced. When you see that traffic is being forwarded as it should, add the other 

servers. 

It is also possible to forward traffic from the load balancer to the Configuration 

Console. See the section “Forwarding Traffic from the Load Balancer to the 

Configuration Console” on page 99 for instructions on how to set this up. 

7.5 Kerberos Authentication 

In a clustered environment where Kerberos authentication is used to authenticate 

users, the load balancer forwards all Kerberos authentication information to the 

Spotfire Servers. No configuration on the load balancer is needed for this, but there 

are certain considerations that must be taken into account when Kerberos 

authentication is set up: 

• Two Service Principal Names must be created for each Spotfire Server as well as 

for the load balancer. 



• One keytab file must be created. This must use the fully qualified Service 

Principal Name of the load balancer. 

• This keytab file must be copied to each Spotfire Server. 

• When Kerberos authentication is set up in the configuration console, the fully 

qualified Service Principal Name of the load balancer must be provided. 

For more information about how to set up Kerberos in the Spotfire system, refer to the 

section “Kerberos” on page 69. 

7.6 X.509 Client Certificate Authentication 

To set up X.509 Client Certificate Authentication, a server certificate needs to be in 

place. In a clustered environment, the clients see the load balancer as the server, and 

the server certificate must therefore be created for and installed on the load balancer. 

To work properly, the CA certificate must also be installed on the load balancer. See 

the section “Setting up HTTPS in a Load Balanced Environment” on page 97 for more 

information about server certificates and how to install them on a load balancer. 

7.7 NTLM Authentication 

In Windows environments, NTLM may be used to authenticate users to the Spotfire 

system. When using load balancing, the load balancer needs to be configured to 

forward NTLM authentication requests and answers. 

Apache httpd needs the module mod_auth_sspi.so in order to forward authentication 

requests and answers. It must be configured to use this module. Add the following to 

the httpd.conf, or to a file included from httpd.conf (for instance mod_auth_sspi.conf): 

 

LoadModule sspi_auth_module modules/mod_auth_sspi.so 

 

 

AuthType SSPI 

SSPIAuth On 

SSPIAuthoritative On 

SSPIPerRequestAuth On 

SSPIDomain domain 

# The name of the authentication realm 

AuthName "Analytics Server through Load Balancer" 

# When offering Basic authentication, the Apache service 

# must be run as a valid local or domain user 

SSPIOfferBasic Off 

# Set SSPIOmitDomain to Off to retrieve user names 

# as "DOMAIN\User" instead of "User" 

SSPIOmitDomain On 



# Convert usernames to lower/upper case 

# SSPIUsernameCase lower 

# SSPIUsernameCase upper 

require valid-user 

# Restrict access to certain users or groups 

# require user "DOMAIN\User" 

# require group "DOMAIN\Group" 

 

See also the Spotfire Server release notes for more information about NTLM 

authentication through a load balancer. 

7.8 Load Balancer Authentication 

The Spotfire Servers can be set to verify the identity of the load balancers by only 

allowing certain hostnames or IP addresses to act as load balancers. 

Also included in load balancer authentication is the filtering of user names propagated 

from the load balancers when using an authentication method such as NTLM. 

Load Balancer Authentication is set in the Configuration Console There are a number 

of options that can be configured. 

Enable Load Balancer 

Authentication 

Request attribute name 

Filter domain name 

expression 

Lower case conversion 

Allowed hostnames 

Decides whether the Spotfire Servers should use load 

balancer authentication or not. 

This is the attribute where the propagated username is 

stored. For example "REMOTE_USER". 

If the attribute where the propagated username is 

stored contains more than the actual username, it is 

possible to apply a regular expression to filter out the 

unwanted parts. For example, if the attribute contains 

"domainname\username", you can use the regular 

expression ".*\\(.*)" to remove "domainname\". 

Specifies whether to convert the propagated username 

to lower case or not. The default is not to convert to 

lower case. 

This is a list of hostnames or IP addresses of 

computers allowed to act as load balancers for the 

Spotfire system. 

7.9 Load Balancer AJP Keyword Restriction 

Apart from Load Balancer Authentication, it is also possible to set up a AJP Connector 

secret keyword for the load balancers to use to authenticate with the Spotfire Servers. 



This is a secret keyword that the load balancers and the Spotfire Servers all know. You 

set this up by doing the following: 

1 Add the keyword to all the Spotfire Servers. 

In the Spotfire Server server.xml, within the section , find 

the Connector configuration: 

 

Add the keyword definition: 

. 

2 Then, add the keyword to the worker,properties file on the load balancer. 

Above the properties for the individual workers, add a keyword for all the workers to 

use: 

# Enable secret keyword 

worker.loadbalancer.secret="SecretKeyword" 

When this is set up, the Spotfire Server will only accept AJP connections from load 

balancers that know the secret keyword. 



8 Authentication and User Directory 

This chapter will outline and explain the different authentication and user directory 

mechanisms available in Spotfire. It will also try to guide and advise the Spotfire 

administrator on which combination of authentication and user directory should be 

used in different situations. For exact instructions on how to configure the different 

methods, see the configuration console and its help. 

8.1 Overview 

Authentication is the function when users prove to the system who they are. The user 

directory is where the Spotfire system stores user and group names used to set and 

verify permissions. The Spotfire system is able to authenticate users internally or with 

external sources. User directory information may be synchronized with an external 

source. These settings are called authentication methods and user directory methods, 

respectively. Which methods and combinations to select depends entirely on factors 

such as number of users and what kind of infrastructure already exists in the network 

in which Spotfire is used. 

This chapter will provide an overview of the different combinations, instructions on 

how to set them up, and advice on which combination to choose, together with 

advantages and disadvantages of the different combinations. 

8.2 Username and Password Authentication 

When users start a Spotfire client, they are normally presented with a login dialog, 

where they supply their username and password. Using single sign-on methods, 

however, this window is bypassed and other forms of authentication are used, such as 

certificates or keys. 

The username and password authentication methods supported by Spotfire are: 

• LDAP Directory 



• Custom JAAS Module 

All of these methods can be configured in the configuration console. 

For all methods, usernames are always stored in the Spotfire Database. When using an 

external authentication method, passwords and/or other authentication information is 

stored elsewhere, such as on an LDAP server or a Windows NT Domain Controller. 



8.2.1 LDAP 

With this authentication method, users are authenticated with an LDAP server, such as 

Microsoft Windows Active Directory or Sun Java System Directory Server. To be able 

to use this method, you must have a working LDAP server. When users log in using 

this method, their usernames are automatically stored in the Spotfire Server database, 

but all other authentication information, such as passwords, resides only on the LDAP 

server. LDAP authentication is recommended when an LDAP server exists in the same 

network as the Spotfire server and you want to use the benefits of not having to add 

users manually to the Spotfire system. If external authentication is wanted or required, 

this is the recommended solution. This method can also be combined with single signon, 

using Kerberos keys. 

When using LDAP, you need to provide Spotfire Server with certain information. 

Some are selectable in dropdown menus in the configuration console, while others you 

have to provide as text. Below is a list of the information needed. 

Server Type 

Protocol 

Hostname 

Port 

Username and Password 

Specifies the brand of your LDAP directory server 

(dropdown list). 

Specifies whether to use LDAP (clear-text) or LDAPS 

(encrypted). 

The hostname of your LDAP directory server. You can 

add more servers (such as more domain controllers 

within the same domain) 

The port on which the LDAP Directory Server 

communicates on. 

Specifies a user that is able to connect to the LDAP 

directory server and browse user and group 

information. 

If you are using a Microsoft LDAP directory, the 

username is simply the name of the user. 

If you are using a Sun LDAP directory, the username 

field must include the user's UID, OU, and DC. For 

example 

uid=malcolm,ou=captains,dc=serenity,dc=firefly,dc=c 

om. 

Note: If you do not provide a context (see below), it is 

important that you use the fully qualified user name 

here. 



Context 

Referral mode 

Username attribute 

Authentication attribute 

Custom LDAP Properties 

This option specifies which context or contexts of the 

LDAP directory you wish to read users from. A 

context can be an Organizational Unit, a Common 

Name, or any other container containing users. Use the 

Browse button to browse and select from the LDAP 

directory tree. You can also type the name of a context 

directly into the field. 

In a large LDAP Directory, different parts of the 

directory tree may be stored on different servers. 

When a search for users is made on one server, the 

result can therefore be a referral to a different server. 

This setting decides whether to conduct a follow-up 

search for the users in question on the referred server. 

The options are Follow, Ignore or Throw. The default 

and recommended value is Follow. 

In an LDAP Directory, a number of attributes are 

stored for each user. The actual username can be called 

different things on different brands of LDAP servers. 

If you select one of the LDAP directory server types 

listed under Server Type, this option will be preselected, 

but if you use a custom LDAP directory 

server, you will need to specify which user attribute is 

the username. 

This option specifies which user attribute should be 

used to authenticate the user. In almost all cases, this is 

the same as Username attribute and should not be 

specified. 

If you authenticate with a custom LDAP server, you 

may in some cases need to specify custom LDAP 

properties here. In most situations, however, you may 

leave this blank. 

If you lack any of this information, you need to speak to the person in charge of the 

LDAP system within your organization that can assist you before you can set up 

LDAP. 

8.2.2 Spotfire Database 

With this authentication method, all usernames and passwords are stored in the 

Spotfire database. This is the “stand-alone” solution, where no external authentication 

is used. No external configuration is required to set this up, but in return all users must 

be manually added using the Administration Manager tool found in the Spotfire client. 

This is recommended when no existing infrastructure can be used, or when the 

Spotfire system should be independent of any other systems. 



8.2.3 Windows NT Domain 

With this authentication method, users are authenticated with a Windows NT Domain. 

To be able to use this method, you must have a working Windows NT 4 Server 

Domain Controller or a Windows Server 2000 (or later) Domain Controller running in 

Mixed Mode. When users log in using this method, their usernames are automatically 

stored in the Spotfire database, but all other authentication information, such as 

passwords, resides only on the Windows NT Domain Controller. This solution should 

only be used in combination with legacy Windows NT 4 environments. To set it up, 

you need to provide the name of the domain in the configuration console. 

8.2.4 Custom JAAS Module 

The authentication methods above are all implemented as Java Authentication and 

Authorization Services (JAAS) modules. Spotfire also supports third-party JAAS 

modules, and you may therefore use a JAAS module of your own, or one or from a 

third-party supplier. Such a module must use username and password authentication 

(specifically, it must use NameCallback and PasswordCallback methods) to be used in 

Spotfire. You must specify the following options in the configuration console: 

Implementation Class 

Flag 

Key value pair 

This option specifies the name of your custom JAAS 

module. 

This option specifies how flags are to be handled. 

This option can contain any other key value pair that 

your custom JAAS module needs or can handle. 

If you lack any of this information, you need to speak to the person that provided you 

with the Custom JAAS module and that can assist you before you can set up Custom 

JAAS authentication. 

Note: When using a custom JAAS module, you need to place the module file in the 

/tomcat/webapps/spotfire/WEB-INF/lib directory on all 

Spotfire Servers. 

8.3 Single Sign-on Authentication 

With a single sign-on solution, users do not authenticate using username and password 

when they start Spotfire. Instead, their Windows login or a client certificate is used to 

verify the user. Spotfire is able to handle a number of different single sign-on 

solutions: 

• Kerberos 

• X.509 Client Certificate 

• NTLM (NT LAN Manager version 1) 

All three methods are configurable in the configuration console. 



8.3.1 Kerberos 

Kerberos is a single sign-on protocol that sends encrypted user information from a 

client across the network to the authentication server. Kerberos works in LDAP 

environments and is considered to have strong security. If you intend to use Spotfire in 

an environment where Kerberos is used, this may be a good way of increasing security 

for the Spotfire system. 

Note: In a clustered environment, there are certain considerations that must be taken 

into account. For details about these, see the section “Kerberos Authentication” on 

page 61. 

There are several steps that must be taken to set up Kerberos authentication. The 

following sections outline them step by step. 

8.3.1.1 Prepare the LDAP Server 

How to set up Kerberos with your LDAP server may differ significantly depending on 

what LDAP server you are using. The instructions provided here will work for a 

Windows Active Directory. If you are using a different LDAP solution, you may have 

to provide different settings to the configuration files provided with the Spotfire 

Server. 

In order for the Spotfire Server to authenticate with a Windows Domain using 

Kerberos, the Windows Domain must meet the following prerequisites: 

• All Domain Controllers must run Windows 2003 Server SP1 or later. 

• Microsoft Support Tools must be installed. 

• All computers that will run Kerberos must belong to the same Windows 

Domain. 

• All computers in the domain must have synchronized clocks (this should happen 

automatically when a computer becomes a member of a domain). 

• All Spotfire users must have user accounts in the Windows Domain. 

Note: If the Windows Server is an upgrade of a Windows 2000 server, the user 

accounts may be using encryption mechanisms not supported by Spotfire. Please refer 

to Microsoft documentation to get around this issue. 

The following steps must then be performed: 

1 Configure LDAP authentication for the Spotfire Server (see the section “LDAP” on 

page 66 for instructions on how to do this). Make sure this is working as intended. 

2 Create a Domain user to be the Spotfire service account. This should be a normal 

domain user account, and should be named something easy to remember. Make sure it 

meets the following requirements: 

• Do not enter a First Name, Initial or Last name for the user account. 

• Use the same information in the Full Name field as in the User Logon Name 

field. Make sure there are no spaces in these fields. 



• Check the box Password never expires. All other boxes should be unchecked 

(Note: Make sure to uncheck User must change password at next logon). 

• If you intend to use Kerberos for database authentication (see the section 

“Database Authentication using Kerberos” on page 91), you must also set 

Account is trusted for delegation found on the Accounts tab of the Properties 

dialog. This setting has certain security issues, and therefore you should only set 

it if you intend to do this. 

Next, you must create two Service Principal Names needed for the authentication. 

This requires Microsoft Support Tools. Refer to its documentation for more 

information about this and other tools included in the package. 

Note: In a load balanced environment, you need to create two Service Principal 

Names for each Spotfire Server, and two for the load balancer. You must map all of 

them to the same service account. 

Creating Service Principal Names (SPNs) 

Executing the following commands on one of the Windows Domain Controllers: 

> setspn -A HTTP/myHost.mydomain[:port] myServiceAccount 

> setspn -A HTTP/myHost[:port] myServiceAccount 

Replace the myHost myServiceAccount, and mydomain variables with values 

appropriate in your environment. 

Note: If you use port 80, do not specify port number. 

Example: 

Setting SPNs for the service account "spotsvc" and the computer 

spotserver.research.example.com using the HTTP port 8080. 

> setspn -A HTTP/spotserver.research.example.com:8080 spotsvc 

> setspn -A HTTP/spotserver:8080 spotsvc 

This would result in the following two SPNs: 

• HTTP/spotserver.research.example.com:8080 

• HTTP/spotserver:8080 

Note: All usernames, hostnames, and domain names are case sensitive. Take special 

care when running the commands and editing the files below. 

After you have run these commands, you can verify your setup with the command: 

> setspn -L myServiceAccount 

Example: 

Verifying SPNs for the service account “spotsvc”. 

> setspn -L spotsvc 

Registered ServicePrincipalNames for 

CN=spotsvc,CN=Users,DC=research,DC=example,DC=com: 



HTTP/spotserver:8080 

HTTP/spotserver.research.example.com:8080 

Create Keytab Files 

The next step is to create keytab files, which the Spotfire Server(s) will use to 

authenticate using Kerberos. This is also done with a tool that comes with Microsoft 

Support Tools, called ktpass.exe. You can run this command on one of your Domain 

Controllers and then copy the created files to the Spotfire Server(s). 

Note: In a clustered environment, create one keytab file, and use the long principal 

name of the load balancer, not one of the Spotfire Servers. 

Always name the file spotfire.keytab, as shown below. Run the command, including 

all the text on one line, like this: 

> ktpass /princ HTTP/myHost.mydomain[:port]@MYDOMAIN 

/mapuser myServiceAccount /ptype krb5_nt_principal /crypto rc4-hmac-nt 

/out spotfire.keytab /pass Password 

Replace the myServiceAccount, myHost 

appropriate values. 

mydomain, and Password variables with 

Example: 

Generate a keytab file for the Spotfire server spotserver.research.example.com running 

on port 8080 in the Windows domain RESEARCH.EXAMPLE.COM (note the upper 

case) with the password Pa55w0rd: 

> ktpass /princ HTTP/spotserver.research.example.com:8080@RESEARCH.EXAMPLE.COM 

/mapuser spotsvc /ptype krb5_nt_principal /crypto rc4-hmac-nt 

/out spotfire.keytab /pass Pa55w0rd 

Install Keytab Files 

Once the keytab files are created with the above examples you need to install them on 

the Spotfire Servers. For each Spotfire Server, the keytab file should be placed in the 

directory 

/jdk/jre/lib/security/ 

Note: This file contains important security information that should not be shared. It is 

recommended that you use caution when copying the files to the destination servers. If 

possible, a memory stick or similar should be used to avoid insecure network file copy. 

You should also limit access to the file once in place. Only the Service and the 

Administrator accounts on the Spotfire Server need to be able to read and write to it. 

Also note that if, at any point, you change the password for Spotfire service account, 

Kerberos will stop working and you will have to re-create the keytab files with the 

new password. 

8.3.1.2 Configure the Spotfire Server(s) to Use Kerberos 

To enable Kerberos on the Spotfire Server(s) there is one configuration file that needs 

to be modified. This chapter will outline what changes need to be made to this file. For 

complete reference of the file, see the section “krb5.conf” on page 137. 



krb5.conf 

This file is located in /jdk/jre/lib/security/ and contains 

information about the Kerberos realm and Windows Domain. the following values 

need to be changed: 

• MYDOMAIN: This is the Kerberos realm. It is equal to the Windows Domain 

and written in upper case. 

• mydomain: This is the Windows Domain. It is written in lower case. 

• mydc: This is the name of the domain controller. It is written in lower case. 

Note: Make sure to use correct case for these values. 

Copy this file to all Spotfire Servers. 

Verify that the Keytab Files Work 

The file spotfire.keytab should now be in the directory 

/jdk/jre/lib/security/ 

In the folder jdk/jre/bin there are a number of tools that can 

help you verify and troubleshoot the spotfire.keytab file. 

You can verify that the spotfire.keytab file works as intended by entering the following 

command in a command prompt on the Spotfire Server: 

> kinit.exe -k -t spotfire.keytab HTTP/myServer.mydomain[:port]@MYDOMAIN 

If the spotfire.keytab file is correct, and works as intended, a ticket cache file will be 

created. 

Example for Windows Server 2008: 

C:\Users\\krb5cc_ 

Important! As soon as you have verified that the ticket cache was created, you must 

delete the ticket cache file. 

You can also check the contents of the spotfire.keytab file using the following 

command. It will list the principal name and security credentials. 

> klist.exe -k -t -K spotfire.keytab 

For other troubleshooting tools, see Microsoft documentation about Kerberos. 

Configuration Console 

After everything is prepared on the Domain Controllers and Spotfire Servers, you need 

to configure the Spotfire system to use Kerberos. This is done in the configuration 

console. You need to specify the Server Principal Name that you have created for the 

Spotfire server, for example HTTP/spotserver.research.example.com. 



For more information on how to use the Configuration Console, see its help. 

Note: When configuring Kerberos authentication in a load balanced environment, 

provide the fully qualified Service Principal Name of the load balancer, not any of the 

Spotfire Servers. 

8.3.2 X.509 Client Certificate 

With this authentication method, users are authenticated through an automatic 

transcript of an X.509 Client Certificate from the Spotfire client to the Spotfire Server. 

When users log in using this method, their usernames are automatically stored in the 

Spotfire database, and instead of passwords, the certificates are used, creating a single 

sign-on solution. A prerequisite of this authentication method is that the Spotfire 

Server, or the load balancer, if present, must be configured to use the HTTPS protocol 

to communicate with the clients. See the sections “Setting up HTTPS on a Spotfire 

Server” on page 86 and “Load Balancer Configuration” on page 60 for more 


To configure Spotfire to use X.509 Client Certificates, the following steps must be 

performed: 

1 Obtain or create a client certificate. 

2 Install the certificate onto clients. 

3 Configure a server to trust the client certificates. 

4 Configure the servers to require client certificates. 

5 Configure a load balancer, if present, to forward the client certificates to the server. 

6 Configure the servers to use client certificates to authenticate users. 

Note: If you perform only steps 1 through 4, the server will require client certificates, 

but can still be configured to use a username and password login mechanism. If 

required, this would provide a very secure solution. 

Obtain or Create a Client Certificate 

How to obtain or create a client certificate is different for every provider. Please turn to 

your provider for information about this. In the section “Creating and Installing a Self- 

Signed Client Certificate” on page 95, an example of how to create a self-signed 

certificate using Microsoft Certificate Services is outlined. 

Install the Certificate onto Clients 

Installing a certificate is normally done with Internet Explorer on the client. By 

connecting to the web page of the certificate provider, it should be possible to select to 

install the certificate. See the section “Creating and Installing a Self-Signed Client 

Certificate” on page 95 for an outline of how to do this with a self-signed certificate 

created by Microsoft Certificate Services. 

Configure a Server to Accept the Client Certificates 



For the servers to accept the client ceritificates, it must be told to trust the certificate of 

the certificate authority that issued them. In order for this to happen, you must export 

the certificate authority certificate (CA certificate) to file and import it to a truststore 

that the Spotfire Servers can read. Once you have the CA certificate in a file on the 

Spotfire Servers, issue the following command to create a truststore and import the CA 

certificate to it: 

/jdk/bin/keytool.exe -importcert -v -file -keystore 

castore.jks. 

clientAuth=”true” 

The truststore file castore.jks can be placed anywhere. You must add the path to it, its 

password and its type to the file server.xml. See the next step for instructions on how 

to do this. 

Configure a Server to Require Client Certificates 

To configure a server to require client certificates you must edit the file server.xml, 

located in the directory server installation dir>/conf. 

In the Connector definition that you created when you configured the server to use 

HTTPS, add the following: 

You must also add the path to the truststore, its password, and type to server.xml. Also 

within the Connector definition, add the following: 

truststoreFile= 

truststorePass=password 

truststoreType=”JKS” 

Configure a Load Balancer 

To configure a load balancer to redirect client certificates, see the section “X.509 

Client Certificate Authentication” on page 62 

Configure the Servers to Use Client Certificates to Authenticate Users 

To configure the servers in the cluster to use client certificates to authenticate users, 

open the configuration console, select the tab called Authentication and select X.509 

Client Certificate as the Login Method. 



8.3.3 NTLM 


TIBCO Spotfire Server 3.2 introduces support for NTLMv2. You 

should consider switching to "NTLM v1/v2" that supports both v1 and 

v2. The instructions below explain how to set up this version, not the 

old. If you wish to continue using "NTLM v1 only" you must copy the 

files jcifs.jar and jcifs-ext.jar from /tomcat/ 

webapps/spotfire/WEB-INF/lib to /tomcat/ 

webapps/spotfire/WEB-INF/lib. 

With this authentication method, users are authenticated with a Windows Domain. 

Setting up NTLM authentication involves three steps: 

1 Creating one or more computer service account in your Windows Domain. 

2 Enabling NTLM authentication for your cluster in the Configuration Console. 

3 Configuring NTLM in either the Configuration Console or on each Spotfire Server (or 

both). 

If you have only one server in the Spotfire system, you can configure all settings in the 

Configuration Console. If you have more than one server, however, you must 

configure some or all settings on each Spotfire Server. 

Note: If you have a load balancer in front of your cluster, you must set up NTLM on 

the load balancer rather than on the Spotfire Servers. See the section “NTLM 

Authentication” on page 62 for more information about this. 

Below are comprehensive instructions for each step. 

Creating a Computer Service Account in Your Windows Domain 

Creating computer accounts in a Windows Domain is done using the Microsoft 

Management Console snap-in Domain Users and Computers. If you do not have 

access to this tool, or if you are unfamiliar with how to use it, please speak to your 

Windows Domain administrator. 

In this tool, create a new computer account. See Microsoft documentation for details 

on how to do this. 

Note: Adding a real computer or re-using an existing account name will not work and 

may cause problems for those accounts and computers. Always create a new account 

by selecting “New computer account”. 

When you have created a new computer account, you need to set a password for this 

account. Unfortunately, this is not possible to do in the Microsoft Management 

Console. In the directory /tomcat/bin there is a vbs script 

called SetComputerPass.vbs. This is an example of how to run the script: 

C:\> cscript SetComputerPass.vbs "cn=spotfireserveruser,cn=computers,dc=yourdomaincontroller,dc=yourorganization,dc=com" 



Note the quotation marks. Here the arguments spotfireserver-user, computers, 

yourdomaincontroller, yourorganization and com reflect a Windows Domain. Your 

Windows Domain may look different. If you do have this information, ask your 

Windows Domain administrator. You will be prompted for the password. If you 

receive the error message 

C:\tibco\tss\3.2.2\tomcat\bin\SetComputerPass.vbs(12, 1) Microsoft VBScript runtime 

error: 

ActiveX component can't create object: 'ScriptPW.Password' 

your system is lacking a component required for password prompting. If this happens, 

you need to edit the SetComputerPass.vbs script and specify the password here. 

Comment out the three lines that read 

Set objPassword = CreateObject("ScriptPW.Password") 

WScript.StdOut.Write "Password:" 

strPassword = objPassword.GetPassword() 

by adding a ' character before them, so that they look like this 

'Set objPassword = CreateObject("ScriptPW.Password") 

'WScript.StdOut.Write "Password:" 

'strPassword = objPassword.GetPassword() 

and add the following line directly below: 

strPassword = “service.account.password” 

and replace the string service.account.password with a long and random password. 

When you have run the script, you should make a note of the password and remove the 

script with the password in it. 

Note: You must be a member of the Account Operators in order to run this script 

successfully. If you get the error message “Microsoft VBScript runtime error: 

Permission denied”, the most likely cause is that you are not. 

Enabling NTLM Authentication for Your Cluster in the Configuration Console 

In the Configuration Console, select the Authentication Tab and select NTLM v1/v2 

as Login Method. 

Configuring NTLM 

Once you have enabled NTLM in the Configuration Console, you are ready to 

configure the settings the Spotfire Servers need to communicate with the Windows 

Domain. 

If you have only one Spotfire Server, this can be done entirely in the Configuration 

Console. 

If you have more than one Spotfire Server, you must configure settings on each 

Spotfire Server, in order to have a unique configuration for each Spotfire Server. You 



can choose to configure all settings on each server, or to configure the settings that 

apply to the entire cluster in the Configuration Console and only the settings unique to 

each server on the actual server. Which of these options you select can depend on 

many factors in your Spotfire system and Windows Domain. 

The settings that need to be unique for each server are how the Spotfire Server 

authenticates with the Windows Domain. This can be achieved either by creating and 

specifying different Service accounts, or by using the Service accounts for all servers, 

but using different NETBIOS names for this account. For most situations, it is 

recommended to use different Service accounts. 

If you choose to configure some settings in the Configuration Console and some on 

each server, simply leave the settings that you will set on each Spotfire Server blank in 

the Configuration Console. 

On the same tab where you enabled NTLM, there are a number of settings that you 

need to specify. 

DNS domain 

Resolve DNS domain 

Service account name 

Service password 

AD site 

Specifies the DNS domain name of your Windows 

Domain. 

Example: yourorganization.com. 

Note: If for some reason you cannot specify a domain 

here, you can specify a hostname of a Domain 

Controller instead. If you do this, set Resolve DNS 

domain to No. 

Specifies whether the name specified in DNS domain 

should be considered a domain name or a hostname. 

Specifies the username of the prepared computer 

service account set up to perform NTLM 

authentication. 

Example: spotfiresrv$@yourorganization.com 

Note: The local part of the account name (spotfiresrv) 

in the example above, must not exceed 15 characters. 

Also note the dollar-sign ($) after the local part of the 

name. 

Specifies the password of the prepared computer 

service account set up to perform NTLM 

authentication. This password will be stored encrypted 

in the Spotfire Database. 

Specifies the Active Directory Site where the Spotfire 

system is located. This setting is optional, but can 

potentially increase performance. 

Example: organization-got 



DNS servers 

DNS cache TTL (ms) 

Specifies the IP addresses DNS servers associated 

with your Windows Domain. Separate multiple servers 

with commas. 

Example: 192.168.1.1,192.168.1.2 

Specifies how long name server lookups should be 

cached. If not set, defaults are used. 

To configure each Spotfire Server, you must edit the file web.xml in the folder 

tomcat/webapps/spotfire/WEB-INF on each Spotfire Server. 

This is an xml file that you can edit in a text or xml editor, and each parameter is set 

like this: 

 

parameter.name 

parameter.value 

 

These are the settings you can configure: 

jespa.service.account.name 

jespa.service.password 

jespa.encrypted.service.passw 

ord 

jespa.localhost.netbios.name 

jespa.dns.domain 

jespa.resolve.dns.domain 

jespa.ad.site 

jespa.dns.servers 

jespa.dns.cache.ttl 

Corresponds to the Service account name parameter 

as specified above. 

Corresponds to the Service password parameter as 

specified above. 

Specifies the encrypted Service password. See below 

for instructions on how to set this parameter. 

Specifies the NETBIOS version of the Service acount 

name. If this is not set, a default name based on the 

Service account name is used. 

Example: spotfiresrv1 

Note: This name may not exceed 15 characters. 

Corresponds to the DNS domain parameter as 


Corresponds to the Resolve DNS domain parameter 

as specified above. 

Corresponds to the AD site parameter as specified 

above. 

Corresponds to the DNS servers parameter as 


Corresponds to the NS cache TTL (ms) parameter as 




Example: 

 

jespa.service.account.name 

spotfiressrv$@yourorganization.com 

 

When you have set these parameters, start the Spotfire Server. 

If you have set a non-encrypted password, you must now replace it with an encrypted 

version. 

Find the log file /tomcat/logs/spotfire/dss.log and open it. In it, 

you will find a warning that says the following: 

WARN 2010-05-20 14:30:15,401 [*Initialization*] server.security.JespaAdapter: 

Unencrypted jespa.service.password found in web.xml, replace with 

jespa.encrypted.service.password set to a+iMktMf8m6lvyf90Zia8hbe6/eVh2Mo 

The bold text above is an encrypted version of the password. In the file web.xml, 

replace the jespa.service.password parameter with a jespa.encrypted.service.password 

with a value of the text string from the log file. 

Example: 

 

jespa.encrypted.service.password 

a+iMktMf8m6lvyf90Zia8hbe6/eVh2Mo 

 

Note: For security reasons, it is important that you replace the jespa.service.password 

parameter with the encrypted version. Do not keep the unencrypted password in the 

web.xml file. 

When this is done, NTLM authentication should work in the Spotfire system. 

Note: It is not possible to delegate NTLM authentication. This means that even if you 

set up your Spotfire Server(s) to authenticate users with NTLM and your database 

server also uses NTLM (Integrated Authentication), the Spotfire Server will always 

authenticate with the database using the Domain User it is running as and never the 

logged in Spotfire user. If you need user delegation, you must use a single-sign on 

method that supports this, such as Kerberos. See the section “Using Kerberos 

Authentication with Delegated Credentials” on page 120 for more information about 

using delegation with Kerberos. 

8.4 User Directory 

When users have been authenticated, information about them is loaded from the user 

directory. This information is stored in the Spotfire database and holds information 

about groups and group membership. These users and groups can then be used to set 

up permissions in the Administration Manager, found in the Spotfire client. 



To simplify administration, it is possible to automatically synchronize user names and, 

optionally, group membership from an external source. Spotfire is able to synchronize 

users from the following external sources: 

• An LDAP directory 

• A Windows NT Domain Controller 

As in the case of authentication, the first option can be a Windows Domain Controller 

or a Sun Java Directory Server, and the second a Windows NT4 Domain Controller. 

User directory synchronization is a good way to simplify user configuration, as users 

that exist in the LDAP directory or Windows NT Domain can automatically be used in 

the Spotfire system as well. You can specify which users to synchronize by adding 

filters, so that you do not synchronize your entire LDAP tree or Windows NT Domain. 

If users are synchronized from an LDAP directory, you can also configure 

synchronization of groups. In this scenario, both users and the groups they belong to in 

the LDAP tree are synchronized, providing even simpler administration of users. The 

imported groups exist in Spotfire as any other group, but cannot be modified. In order 

to change their permissions, however, you can add them to a regular, non-imported 

group. Synchronization of groups is not available if you synchronize with a Windows 

NT Domain Controller. 

To set up user directory synchronization, you must have a user in the LDAP directory 

or the Windows NT Domain that has the appropriate permissions for reading user and 

group information. The login information of this user, together with some other 

information, is then entered into the configuration console. See the configuration 

console help for details on the various settings. 

You must specify a number of options in the configuration console for synchronization 

with an LDAP directory or a Windows NT Domain Controller. These are specified 

below. 

LDAP Directory 


Protocol 

Hostname 

Port 

Specifies the brand of your LDAP directory server. 

(dropdown list). 

Specifies whether to use LDAP (clear-text) or LDAPS 

(encrypted) (dropdown list). 

The hostname of your LDAP directory server. You can 

add more servers (such as more domain controllers 

within the same domain). 

The port on which the LDAP Directory Server 

communicates. 




Context 

Request controls 

Page size/Import limit 

Referral mode 

Enable group synchronization 

Specifies a user that is able to connect to the LDAP 

directory server and import user and group 

information. If you are using a Microsoft LDAP 

directory, the username is simply the name of the user. 

If you are using a Sun LDAP directory, the username 

field must include the user's UID, OU, and DC. For 

example 

uid=malcolm,ou=captains,dc=serenity,dc=firefly,dc=c 

om. 

Note: If you do not provide a context (see below), it is 

important that you use the fully qualified user name 

here. 

This option specifies which context or contexts of the 

LDAP directory you wish to read users from. A 

context can be an Organizational Unit, a Common 

Name, or any other container containing users. 

When searches for users and groups are performed, 

these may sometimes result in huge lists. In some 

LDAP directory types, it is possible to limit the 

number of results returned, or to divide them into 

several pages. This option specifies which, if any, 

controls like this should be used. If set to Probe, the 

Spotfire system will ask the LDAP directory servers 

for its capabilities. For most types of directory servers, 

the default value should be used. 

This setting will set the size of each page of returned 

results, or the total number of search results that 

should be imported, depending on the Request 

controls setting. For no limit at all, select the value -1. 

To avoid problems, it is recommended to configure 

Referral mode and Search filter, if possible, so that the 

number of search results will be reasonable. 

In a large LDAP Directory, different parts of the 

directory tree may be stored on different servers. 

When a search for users is made on one server, the 

result can therefore be a referral to a different server. 

This setting decides whether to conduct a follow-up 

search for the users in question on the referred server. 

The options are Follow, Ignore, Throw, and Default. 

This option specifies whether or not groups should be 

synchronized. 



Server supports MemberOf 

Group synchronization 

Synchronization schedule 

User search filter 

Username attribute 

Group name attribute 

Group search filter 

Most LDAP servers store all groups a user is a 

member of in the user object. This is how the Spotfire 

system finds members of groups to synchronize. Some 

LDAP implementations, however, do not support this 

feature. To perform group synchronization with these 

LDAP servers, the Spotfire system will have to search 

within the group to synchronize for its members, and 

then perform a second search to find the correct 

username attribute for the user. This will increase 

traffic immensely between the Spotfire system and the 

LDAP server, and should only be used if you need 

group synchronization and your LDAP server does not 

support the MemberOf attribute. Note that the major 

LDAP implementations from Microsoft and Sun do 

support MemberOf. If unsure, select Yes. See also the 

option Member attribute. 

This option specifies which groups should be 

synchronized. 

This options specifies how often groups should be 

synchronized. For instance, if you want to synchronize 

groups every Monday at 09:00, the schedule should 

read "0 9 * * Monday". 

This syntax is a subset of crontab syntax. Specifically, 

"/" (slash) is not supported in any field. For more 

information about crontab syntax, see the Wikipedia 

article http://en.wikipedia.org/wiki/Cron and any of 

the pages it refers to. 

To further limit what part of the LDAP directory tree is 

searched for users, you can add additional search 

filters in addition to Context above. 

In an LDAP Directory, a number of attributes are 

stored for each user. The actual username can be called 

different things on different brands of LDAP servers. 

If you select one of the LDAP directory server types 

listed under Server Type, this option will be preselected, 

but if you use a custom LDAP directory 

server you need to specify which user attribute is the 

username. 

As with Username attribute, this option specifies 

which attribute is the group name. 

To further limit what part of the LDAP directory tree is 

searched for groups, you can add more search filters in 

addition to Contexts above. 



Member attribute 

Recursive group search 

Custom LDAP Properties 

This option controls which attribute specifies group 

membership for a user. If Server supports MemberOf 

is set to Yes, this setting is interpreted as an attribute in 

user objects. If Server supports MemberOf is set to 

No, this setting is interpreted as an attribute in group 

objects. 

This specifies whether group searches in the LDAP 

directory should be recursive or not. As different type 

of LDAP directories behave differently in this regard, 

this option is pre-selected and cannot be changed if 

you have not selected to use a custom LDAP server. 

If you authenticate with a custom LDAP server, you 

may in some cases need to specify custom LDAP 

properties here. In most situations, however, you may 

leave this blank. 

Windows NT Domain 

Domains 

Synchronize time (minutes) 

Defines the Windows Domains where the user 

information is stored. The user information will be 

synchronized from this domain into the Spotfire 

database regularly. You can add several domains. Note 

that all domains you add will be in use; users will be 

synchronized from any of the domains configured. 

Specifies, in minutes, how often the users should be 

synchronized from the Windows NT Domain, in 

minutes. The default is 60 minutes. 

Note: If you have a large domain and do not need user 

synchronization as often as once an hour, you should 

consider increasing this value for performance 

reasons. 

If you lack any of this information, you need to speak to the person in charge of the 

LDAP system or Windows NT domain within your organization that can assist you 

before you can set up User Directory synchronization. 

Note: If you use this feature in a load balanced environment, you must manually add 

configuration to the Spotfire Servers, to prevent them from all synchronizing with the 

LDAP directory. See the section “Preventing User Directory Synchronization” on 

page 101 for more details on this. 


Advanced Procedures 

9 Advanced Procedures 

9.1 Overview 

This section describes advanced manual procedures for setting up various features 

supported by the Spotfire system. Many of the procedures assume prior knowledge 

about LDAP directory, Kerberos, Windows Server, Apache httpd, etc. For detailed 

information about how these various technologies work and how they are set up, 

please refer to the respective documentation for each technology. 

9.2 Installing Spotfire Server Silently Using 

Pre-defined Parameters 

UPGRADING FROM 3.0 or 3.1 TO 3.2? 

If you are upgrading from Spotfire Server 3.0 or 3.1 and wish to 

preform a silent install, you must run the installation and upgrade 

separately. When you record the installation, do not launch the upgrade 

tool at the end of the installation. 

It is possible to run the Spotfire Server installer silently, using predefined parameters. 

This is useful when you wish to install several servers with the same setup. 

By running the installer from a command prompt, you can first record the settings you 

make in the installer dialogs and save these to a properties file. 

You can then run the installer from a command prompt and specify the properties file. 

This will cause the installer to execute silently without displaying any dialogs, and it 

will use the information specified in the properties file. 

You can also edit the properties file in a text editor before you perform a silent install. 

Note: Do not attempt to run the Upgrade tool silently, or have a silent install start it. 

 

To record type: 

install.exe -r c:\installer.properties 

Note: You must specify an absolute path to the file! 

 

To run the installer silently: 

install.exe -i silent -f installer.properties 

Note: If no path is specified to the properties file, it is assumed it is located in the same 

folder as the install.exe. 

Example: 



Included in the server distribution, there is an example file called silent.properties. 

The exact content of this vary on the platform you have chosen. For Win32 the file 

looks like this: 

# Thu Dec 17 11:09:57 CET 2009 

# Replay feature output 

# --------------------- 

# This file was built by the Replay feature of InstallAnywhere. 

# It contains variables that were set by Panels or Consoles. 

#Selected Features. 

# 'Server' selects the Analytics Server. 

# 'Admin' selects the Management Console. 

#---------------------- 

CHOSEN_INSTALL_FEATURE_LIST=Server,Admin 

#Third Party Components 

#---------------------- 

THIRD_PARTY_YES=1 

THIRD_PARTY_NO=0 

#Installation Folder 

#------------------- 

USER_INSTALL_DIR=C:\\tibco\\tss\\3.2.2 

#OS Architecture 

#--------------- 

IS_32BIT_OS=1 

IS_64BIT_OS=0 

#Windows Service 

#--------------- 

WINDOWS_SERVICE_CREATE_START=1 

WINDOWS_SERVICE_CREATE_NO_START=0 

WINDOWS_SERVICE_NO_CREATE=0 

#Spotfire Server Ports 

#--------------------- 

SERVER_PORT=80 

CONTROLLER_PORT=8078 

#Configuration Port 

#------------------ 

CONSOLE_PORT=8080 

#Upgrade 

#------- 

LAUNCH_UPGRADE_TOOL=\"\" 

LAUNCH_UPGRADE_TOOL_1= 

LAUNCH_UPGRADE_TOOL_BOOLEAN_1=0 

Note that you can choose whether to run the upgrade tool or not, and that the upgrade 

tool will be run interactively, not silently, if you choose to launch it from a silent 

install. 



9.3 Setting up HTTPS on a Spotfire Server 

By default, Spotfire uses the HTTP protocol for communication between clients and 

the server. To achieve a higher level of security, it is possible to use the HTTPS 

protocol instead, ensuring encryption between clients and the server. 

To configure a Spotfire Server to use the HTTPS protocol, you must perform these 

steps: 

1 Obtain or create a server certificate used to encrypt the traffic. 

2 Install the certificate on the server. 

3 Configure Spotfire to communicate over HTTPS. 

Obtain a Server Certificate 

The method for obtaining or creating a server certificate is different for every provider. 

Please turn to your provider for information about this. In the section “Creating a Self- 

Signed Server Certificate” on page 87, an example of how to create a self-signed 

certificate using Microsoft Certificate Services is outlined. 

Install the Certificate on the Server 

To install the certificate on the Spotfire Server, place it anywhere on the disk, 

preferably in a subfolder to the Spotfire Server installation directory, such as 

/certs/. 

Configure the Server to Communicate over HTTPS 

To make the server communicate using the HTTPS protocol, you must now edit the 

main configuration file of the server. This is found in the directory 

/tomcat/conf/ and is called server.xml. You need to find the 

section that defines the service “Spotfire”, and within that the section that defines the 

Connector. This section begins with . Replace this section with the 

following: 

 

Be sure to replace [path to server’s private certificate] with the actual path to 

the certificate, and [password] with the password to the keystore. If you have obtained 



the certificate from some other place than Microsoft Certificate Services, the type may 

differ. 

Note: The password is stored in cleartext. You should secure the file and/or the server 

to prevent users from accessing it. 

By doing this, you have secured communication between Spotfire clients and the 

Spotfire server. It is also strongly recommended to encrypt communication with the 

configuration console and the controller by doing the same thing to the Connector 

sections within the “ConfigurationConsole and the “SpotfireController” Services 

respectively. Make sure to select different ports for each Service. 

For a more detailed view of the file server.xml, see the section “Server.xml” on 

page 135. 

When you have saved the file, you need to restart the Spotfire Server for the changes 

to take effect. You can then add the server to the cluster in the configuration console. 

Note: If you have configured the Spotfire controller to use HTTPS, make sure to select 

https as the “server protocol” when adding a new server to the cluster. Otherwise, use 

http. 

Encryption in a Clustered Environment 

In a clustered environment, clients communicate using HTTP or HTTPS with the load 

balancer, which then redirects traffic to the servers using the AJP protocol. The AJP 

protocol cannot be encrypted. It is therefore recommended that the load balancer and 

the Spotfire Servers reside on the same secure network, or that other security 

measures, such as tunnel technology, are used. 

To configure the load balancer to use HTTPS, follow the instructions in the section 

“Setting up HTTPS in a Load Balanced Environment” on page 97. 

Note: In a clustered environment, the configuration console communicates with each 

server directly, using the HTTP or HTTPS protocol. For this reason, you might still 

want to configure the servers to use HTTPS if you need the extra security this 

provides. 

9.3.1 Creating a Self-Signed Server Certificate 

In order to use HTTPS, you must have a server certificate on the Spotfire Servers. 

Such a certificate can be obtained from a number of providers. If you are unable to 

obtain such a certificate, or wish to set up a test configuration, you can also create a 

self-signed certificate. How this is done is highly dependent on which certificate 

software you are using. 

Note: These directions assume that you are using Microsoft Certificate Services. 

1 On the Spotfire Server, Start Internet Explorer. 

2 Connect to your Active Directory Certificate Service homepage. For example, 

http:///certsrv/ 



3 Select Request a certificate... > Advanced Request > Submit a certificate request 

to this CA using a form. 

4 Enter username and e-mail. Use the hostname of the Spotfire Server as username. In 

a clustered environment, use the hostname that the clients use to connect to the 

Spotfire cluster. 

5 Mark Purpose as Server Authentication Certificate. 

6 Mark Key as Exportable (but do not check Export Key to File). 

7 Click Submit and acknowledge that a certificate is being requested. 

8 Open the Certification Authority application on the machine where the Certificate 

Server is installed. 

9 Select Certification Authority > Test > Pending requests, where a pending request 

should be available. 

10 Mark the request, right-click and select All tasks > Issue. 

Response: The new certificate should now be visible under "Issued Certificates". 

11 Close the application. 

12 Connect to your Active Directory Certificate Service homepage, for example, 

http:///certsrv/ from the local computer using Internet 

Explorer. 

13 Select Check on a pending certificate > Next. 

Response: A page with the text "Check On a Pending Certificate Request" and 

"Please Select the Certificate Request You Want to Check" is displayed. 

14 Select the Certificate and click Next. 

Response: A page with the text "Certificate Issued” or “The certificate you requested 

was issued to you." is displayed. 

15 Select Install this certificate > Yes > Yes. 

Response: A page confirming that the certificate is installed is displayed. 

16 In Internet Explorer, select Tools > Internet Options. 

17 Select the Content tab. 

18 Click the Certificates button. 

19 Mark the certificate that was issued to you. 

20 Click Export > Next > Yes, export the private key > Next. 

21 Check Include all certificates. 



Comment: There is no need to select “Enable strong protection”. 

22 Select Next. 

23 Enter password for the file. 

24 Specify where the key should be saved. 

25 Select Next > Finish. 

9.3.2 Getting Clients to Trust a CA Certificate 

If you have created a self-signed server certificate, the clients will not trust this 

certificate by default. For this to happen, you need to tell each client to trust the 

Certificate Authority certificate (CA certificate). If you do not, the clients will not use 

the certificate and communication with the server will not be possible. These 

instructions assume that you are using Microsoft Certificate Services. 


http:///certsrv/ with Internet Explorer. 

2 Select Retrieve the CA certificate or certificate revocation list. 

3 Click on the link Install this CA certification path > Yes > Yes. 

Note: Verify that you can connect to the Spotfire Server using https and that the client 

and server trusts each other without producing warnings. 

9.3.3 Additional Windows Vista Settings: 

Windows Vista will by default attempt to check if the certificate is revoked. This 

cannot be done with a self-signed certificate. When this fails, communication between 

the Spotfire client and the Spotfire Server will not work. You must therefore turn this 

feature off. To do this, do the following: 

1 Open Tools > Internet Options in Internet Explorer. 

2 Select the Security tab. 

3 Find the setting “Check for server certificate revocation” and clear it. 

4 Click OK and confirm that you wish to do this. 

9.4 Restricting Access to the Configuration 

Console 

To further increase security, you can restrict access to the configuration console. This 

can be done by a feature built into Apache Tomcat, and is configured in server.xml. 



Note: Restricting access to the Configuration Console is important if you authenticate 

with the Spotfire database using Windows Integrated Authentication. 

Within the ConfigurationConsole section, find the Context definition: 

 

Below it, add a “Valve” definition, so that it looks like this: 

 

 

You can add any IP address or addresses, comma separated (127.0.0.1,192.168.0.1). 

Wildcards are also supported (192.168.0.*). 

If you need to restrict address to hostnames rather than IP addresses, you can do this 

by enabling host lookups. This is done within the Connector definition: 

 

With this enabled, you can add hostnames instead of IP addresses: 

 

 

Note: Host lookups are time and resource consuming. If possible, access restriction 

based on IP address should therefore be used. 

You can of course also restrict access to the configuration console by filtering the 

Configuration Console port (by default 8080) in any firewall or router that the 

configuration console is located behind. 

For further information about the server.xml file, see the section “Server.xml” on 

page 135 and the Apache Tomcat manual, located at http://tomcat.apache.org/tomcat- 

6.0-doc/config/. 

Note that this approach is also valid in a clustered environment. The load balancer will 

retain the IP address of the client when forwarding the request, so that the 

configuration console is able to filter out unwanted traffic. This can therefore be 

combined with the method described in the section “Forwarding Traffic from the Load 

Balancer to the Configuration Console” on page 99. 



9.5 Configuring LDAPS 

In an LDAP environment, where the Spotfire system authenticates users with an 

LDAP directory, it might be a good idea to secure the LDAP protocol using SSL, if the 

LDAP directory supports this. 

To achieve this, you must first set up the LDAP directory to communicate using SSL. 

Refer to your LDAP server manual for instructions on this. 

Then you must get the Spotfire Server(s) to trust this certificate. This is done by 

following steps: 

1 Export the certificate to file and copy it to the Spotfire Server(s) and the configuration 

console machine(s). 

2 With a command prompt or shell, navigate to the directory /jdk/jre/lib/security and execute the keytool command located in the 

/jdk/bin/ directory to import the certificate: 

../../bin/keytool -import -file ldapserver.crt -keystore cacerts -alias spotfire_ldaps 

Replace ldapserver.crt with the name of the exported certificate. 

When prompted, enter the password to the cacerts keystore. The default password is 

“changeit”. 

3 Verify that the certificate has been successfully added by using the keytool command 

again: 

../../bin/keytool -list -keystore cacerts -alias spotfire_ldaps 

When prompted, enter the password to the cacerts keystore. The result of the 

command should be that the certificate is added. 

Once the server certificate is trusted by all the Spotfire Servers, log into the 

configuration console and set Authentication Method to LDAPS. Refer to the 

configuration console help for assistance. 

9.6 Database Authentication using Kerberos 

If your database engine is able to authenticate users using Kerberos, you can let the 

Spotfire Server authenticate with it in this way. 

To set this up, you need to perform a number of manual steps. While it is possible to 

perform these steps on a running Spotfire installation, it is recommended that you do 

them before defining a Spotfire cluster, and before you log into the configuration 

console for the first time. 

You also need to make sure to either be logged into the database server with the user 

created below when creating the Spotfire database, or ensure that you can give this 

user access to the Spotfire database later. Refer to your database engine manual for 

more details on this. 



Note: These steps should all be performed on the machine that runs the configuration 

console. The configuration console will then export these settings to all Spotfire 

Servers when they are added to the cluster. You do not need to modify any files on the 

Spotfire Server(s). 

The steps will first be outlined briefly, and then described in detail below: 

1 Create a user account in the Kerberos environment. 

2 Create a keytab file for the user account. 

3 Create and populate the Spotfire database. 

4 Modify the file krb5.conf. 

5 Create the file databasekerberos.login. 

6 Modify the file java.security. 

7 Modify the file connections.xml. 

8 Log into the configuration console. 

9 Export the Spotfire configuration to file. 

10 Modify the Spotfire configuration export file. 

11 Import the Spotfire configuration. 

12 Add Spotfire Servers to the cluster. 

Create a User Account in the Kerberos Environment 

Start by creating a user account in the Kerberos environment. See the section “Prepare 

the LDAP Server” on page 69 for information about how the user account should be 

set up. 

Create a Keytab File for the User Account 

Use the ktab.exe tool found in the folder /jdk/bin/ to 

ktab.exe -k database.keytab -a 

Note: Use only the username, not the fully qualified username. 

Create and Populate the Spotfire Database 

To be able to use the create_databases script, the database engine needs to accept 

regular login as well as Kerberos login. If it does not, you cannot use this file. Instead, 

you must run the sql-scripts this file calls. See the section “Running Database 

Preparation Scripts Manually” on page 102 for more information about this. 

Modify the File krb5.conf. 



The file krb5.conf needs to be modified according to the same principle as for Spotfire 

client authentication using Kerberos (see the section “krb5.conf” on page 72 for more 

information). 

Create the File databasekerberos.login 

Create a file called databasekerberos.login in the 

/jdk/jre/lib/security/ directory. It should contain the 

following: 

DatabaseKerberos 

{ 

com.sun.security.auth.module.Krb5LoginModule 

required 

debug=true 

storeKey=true 

useKeyTab=true 

keyTab="${java.home}/lib/security/database.keytab" 

principal="MSSQLSrv/spotdb.research.example.com:1433@ RESEARCH.EXAMPLE.COM"; 

}; 

Modify the File java.security 

Add the following to the end of file java.secuity, located in the 

/jdk/jre/lib/security/ directory: 

# Register Java Authentication & Authorization Services (JAAS) configurations 

login.config.url.1=file:${java.home}/lib/security/databasekerberos.login 

Modify the file connections.xml 

Add the following data source definition to the file connections.xml located in 

/webapps/admin/WEB-INF/: 

 

Server.Default 

 


tibcosoftwareinc.jdbc.sqlserver.SQLServerDriver 


spotdb.research.example.com\SPOTFIRE;DatabaseName=spotfire_server 

false 

DYNAMIC_ADAPTIVE 

-1 

0 

600 

false 

true 

0 

 

 


 

 



Note: See the section “Database Connection URL Components and Examples” on 

page 140 for more information about Database Connection URLs. 

Log into the Configuration Console 

Log into the configuration console without providing a username or password. Click 

the button login with the login and password fields empty. 

Export the Spotfire Configuration to File 

In the configuration console, select Export to export the Spotfire configuration to file. 

Modify the Spotfire Configuration Export File 

Using a text or xml editor, add the following text to the authentication tag: 

 

 

 


com.sun.security.auth.module.Krb5LoginModule 

required 

 

 

debug 

false 

 

 

storeKey 

true 

 

 

useKeyTab 

true 

 

 

keyTab 

[Path to KeyTab file] 

 

 

principal 

MSSQLSrv/spotdb.research.example.com:1433@RESEARCH.EXAMPLE.COM 

 

 

 

 

 

Make sure not to modify other content within the authentication tag or any other 

contents of the file. 

Import the Spotfire Configuration 

Import the modified Spotfire configuration by selecting Import in the configuration 

console. 

Add Spotfire Servers to the Cluster 



Add Spotfire Servers to the cluster. This will create a database.xml file for each server 

with the information created above. 

Note: If you added servers to the cluster before setting up Kerberos database 

authentication, you need to remove them from the cluster and add them again. 

When you start the servers, you might want to check the logs located in 

/tomcat/logs/spotfire/ to make sure they are able to 

authenticate with the database properly. 

Verify that the spotfire.keytab File is in Place and Works 

Verify that the spotfire.keytab file created earlier has been moved from the Domain 

Controller and is now placed on the Spotfire Analytics Server in the following 

directory: 

/jdk/jre/lib/security/spotfire.keytab 

Optional: 

In the folder jdk/jre/bin there are a number of tools that can 

help you verify and troubleshoot the spotfire.keytab file. 

You can verify that the spotfire.keytab file works as intended by entering the following 

command in a command prompt on the Spotfire Analytics Server: 

> kinit.exe -k -t spotfire.keytab HTTP/myServer.mydomain[:port]@MYDOMAIN 

If the spotfire.keytab file is correct, and works as intended, a ticket cache file will be 

created. 

Example for Windows Server 2003: 

C:\Documents and Settings\\krb5cc_ 

Important! As soon as you have verified that the ticket cache was created, you must 

delete the file. 

You can also check the contents of the spotfire.keytab file using the following 

command. It will list the principal name and security credentials. 

> klist.exe -k -t -K spotfire.keytab 

9.7 Creating and Installing a Self-Signed 

Client Certificate 

In order to use X.509 Client Certificates, you need to have a client certificate on the 

Spotfire clients. Such a certificate can be obtained from a number of providers. If you 

are unable to obtain such a certificate, or wish to set up a test configuration, you can 



 

 

 

also create a self-signed certificate. How this is done is highly dependent on which 

certificate software you are using. These instructions assume that you are using 

Microsoft Certificate Services. 

Request a Certificate: 


http:///certsrv/ using Internet Explorer. 

2 Request a certificate of the type “Client Authentication Certificate”. 

Comment: If the certificate is used as the only authentication method the username is 

used as the identity. If the user directory is using windows authentication, 

then this should be the shorter alias, e.g., not "John Doe", but "johnd". 

Issue the Certificate: 

1 Open the Certification Authority application on the machine running the Certificate 

Services. 

2 Select Certification Authority > Test > Pending requests, where a pending request 

should be available. 

3 Mark the request, right-click and select All tasks > Issue. 

Response: The new certificate should now be visible under Issued Certificates. 

Close the application. 

Install the Certificate: 

1 Connect to your Active Directory Certificate Service homepage, for example, http:// 

/certsrv/ from the client computer. 

2 Select Check on a pending certificate > Next. 

3 Verify that a Client Authentication certificate is selected. 

4 Click Next. 

Response: A page with the text "Certificate Issued/The certificate you requested was 

issued to you." is displayed. 

5 Select Install this certificate. 

6 Select Yes in the confirmation dialogs. 

Response: A page confirming that the certificate is installed is displayed. 

 

Optional IE Settings: 

Internet Explorer might provide you with a selection box which lets you specify which 

certificate is to be used. To get rid of these certificate selection boxes, do the 

following: 



1 Open Tools > Internet Options in Internet Explorer. 

2 Select the Security tab. 

3 Select Local Intranet. 

4 Click Sites > Advanced. 

5 Add https:// to the list of hosts in this zone. 

6 Click OK. 

7 Select Custom level for the Intranet zone security settings. 

8 Make sure that Don't prompt for client certificate selection when no certificates or 

only one certificate exists is Enabled. 

9 Click OK and confirm that the security settings should be changed. 

Comment: This works if there is only one matching certificate. Thus if there is more 

than one certificate which can be used by the server, there will still be 

selection dialogs. 

9.8 Setting up HTTPS in a Load Balanced 

Environment 

In a clustered environment, the clients see the load balancer as the server. Therefore, in 

order to secure the communication in the Spotfire system, using HTTPS, the load 

balancer needs to be configured to do this. This is achieved by obtaining (or creating) 

a server certificate for the load balancer and instalingl it on the load balancer. You may 

need to convert it first. 

Note: You cannot use a server certificate created for a Spotfire server. A server 

certificate must always be created for the computer it is intended for. 

The following instructions assume that you are acquainted with the Apache httpd and 

its configuration files. It should be seen as an overview of how HTTPS is setup for use 

in load balancing a Spotfire system, not as a tutorial on Apache httpd. For more 

information, please refer to the Apache httpd manual. 

1 Install Apache httpd with ssl support and the mod_ssl.so and mod_jk modules. 

2 Create a self-signed server certificate. 

3 If needed, convert the certificate to a format readable by the load balancer. 

4 Store the converted certificate in the Apache conf directory. 

5 Configure Apache to use the certificate files. 

6 Make your clients trust the CA certificate. 



Install Apache httpd with SSL Support and the mod_ssl.so and mod_jk 

modules 

For exact instructions on how to install Apache httpd, see the Apache manual. 

If you are using an Apache installer, you might be presented with the option of 

creating a self-signed server certificate from within the installer, and have Apache 

automatically configured to use this server certificate. If this is the case, you can skip 

to the step “Make your clients trust the CA certificate”. 

If you are not using an automatic installer, or wish to create and install a different selfsigned 

certificate, continue reading. 

Create a Self-Signed Certificate 

You can create a self-signed certificate for the load balancer using the steps described 

in the section “Creating a Self-Signed Server Certificate” on page 87. 

After creation, save the certificate to file and transfer it to the load balancer. 

Convert the Certificate to a Format Readable by the Load Balancer 

The certificate must be in the Base 64-encoded DER format (PEM) format for Apache 

httpd to be able to read it. If the certificate is created with Microsoft Certificate 

Services, it is in the PKCS #12 format. To convert it, use the openssl command on the 

load balancer. (If this is not installed, refer to http://openssl.org/ or your OS manual for 

instructions on how to install it.) 

openssl pkcs12 -in server.pfx -out server.pem 

Next, the public key in the certificate must be extracted from the converted certificate: 

openssl x509 -in server.pem -out server_cert.pem 

Finally, the private key in the certificate must be extracted from the converted 

certificate: 

openssl rsa -in server.pem -out server_key.pem 

These commands will provide you with three files: server.pem, server_cert.pem, and 

server_key.pem. You will only need the two latter files. 

You also need the CA certificate on the load balancer in the PEM format. If you are 

using a self-signed certificate, the CA certificate should be available for download 

from the same source, usually under “Trusted Root Certification Authorities” or 

similar. If needed, convert the CA certificate to PEM format using the convert 

command above. You do not need to extract anything from it. 

Store the Converted Certificate Files in the Apache Conf Directory 

Copy all the files created above to the directory /conf. 

Configure Apache httpd to Use the Certificate Files 

Add the following lines to the Apache httpd configuration (for instance, to the load 

balancer’s virtual host): 



# Configure SSL 

SSLEngine On 

SSLCertificateFile "conf/server_cert.pem" 

SSLCertificateKeyFile "conf/server_key.pem" 

SSLCACertificateFile "conf/cacert.pem" 

SSLOptions +StdEnvVars +ExportCertData 

Your Apache httpd should now communicate using the HTTPS protocol. 

Make Your Clients Trust the CA Certificate 

This step is identical to that described in the section “Getting Clients to Trust a CA 

Certificate” on page 89. 

9.9 Forwarding Traffic from the Load 

Balancer to the Configuration Console 

In a non-clustered environment, the administator uses the configuration console by 

entering its hostname in a web browser. In a clustered environment this approach is of 

course valid, but it is also possible to reach the configuration console through the load 

balancer. This is beneficial if the Spotfire Servers and the configuration console are 

installed in a network only reachable through the load balancer. 

To set this up using Apache httpd as a load balancer, you need to add the following to 

mod_jk configuration (such as in the file mod_jk.conf): 

JkUnmount /config loadbalancer 

JkUnmount /config/* loadbalancer 

JkMount /config mcworker 

JkMount /config/* mcworker 

“mcworker” is the machine where the configuration console is installed. Its hostname 

is “mc1” in this example. 

Then, you need to add the mcworker to the list of workers in the workers.properties 

file: 

worker.list=jkstatus, loadbalancer, mcworker 

You must also define the mcworker just as you would any other worker in the 

worker.properties file: 

worker.mcworker.type=ajp13 

worker.mcworker.host=mchostname 

worker.mcworker.port=8079 

worker.mcworker.max_packet_size=65536 

worker.mcworker.lbfactor=1 

worker.mcworker.route=[servername]-adm 

Make sure port number and route correspond to the values in the server.xml file on the 

configuration console. See the section “Server.xml” on page 135 for further 

information about this file. 



With this setup, all calls to the configuration console will terminate on the machine 

running the configuration console, known to the load balancer as “mcworker”. See the 

section “Load Balancing” on page 59 for further information about load balancing in 

the Spotfire system. 

Note: It is also possible to create a load balanced system of configuration console 

machines by using the same method as when load balancing Spotfire Servers, 

described in the chapter “Load Balancing” on page 59. This can be beneficial in order 

to avoid the configuration console being a single point of failure. 

9.10 Shared Disk Location in a Clustered 

Environment 

From the Library Administration tool found in the Spotfire client, it is possible to 

import and export content to and from the library. The import and export files are 

stored in a folder specified in the Spotfire Server configuration. 

In a clustered environment, there is no way of being certain which server the client is 

communicating with. Therefore, steps must be taken to ensure that the import and 

export files are always stored in the same folder. 

One method is to use Windows shared folder technology, and set the location of the 

import and export folder to a folder that is shared with all Spotfire Servers. As this 

may not be the most secure option, there is also a method in which you can configure 

the load balancer to always redirect import and export requests to the same Spotfire 

Server. 

To set this up using Apache httpd as a load balancer, you need to add the following to 

the mod_jk configuration (such as in the file mod_jk.conf): 

JkUnmount /spotfire/ws/protected/services/LibraryImportExportService loadbalancer 

JkUnmount /spotfire/ws/protected/services/LibraryImportExportService/* loadbalancer 

JkMount /spotfire/ws/protected/services/LibraryImportExportService worker1 

JkMount /spotfire/ws/protected/services/LibraryImportExportService/* worker1 

“worker1” is the Spotfire Server where import and export files are to be stored. 

Then, you need to add the worker1 to the list of workers in the workers.properties file: 

worker.list=jkstatus, loadbalancer, worker1 

With this setup, all import and export calls from the Library Administration tool will 

terminate on the Spotfire Server worker1. See the section “Load Balancing” on 

page 59 for further information about load balancing in the Spotfire system. 



9.11 Preventing User Directory 

Synchronization 

When you use user directory synchronization with an LDAP directory in a load 

balanced environment, only one Spotfire Server should synchronize from the LDAP 

directory to the Spotfire database. To achieve this, you must add manual configuration 

to the Spotfire Servers that are NOT to synchronize. You do this by adding the 

following to the file web.xml, located in the /tomcat/ 

webapps/spotfire/WEB-INF/ directory: 

 

group.synchronization.disabled 

true 

 

Note: You must add this text to the file web.xml on ALL Spotfire Server but the one 

supposed to perform the synchronization. 

9.12 Configuring X.509 Client Certificates in a 

Load Balanced Environment 

In a load balanced environment, where X.509 Client Certificate authentication is to be 

used, the load balancer needs to be aware of the situation and forward the client 

certificates to the Spotfire Servers. 

The following instructions assume that you are acquainted with the Apache httpd and 

its configuration files. It should be seen as an overview of how HTTPS is setup for use 

in load balancing a Spotfire system, not as a tutorial on Apache httpd. For more 

information, please refer to the Apache httpd manual 

1 Configure the Spotfire system to use X.509 Client Certificate authentication. See the 

section “X.509 Client Certificate” on page 73 for instructions on how to do this. 

2 Configure Apache httpd to communicate using the HTTPS protocol. See the section 

“Setting up HTTPS in a Load Balanced Environment” on page 97 for instructions on 

how to do this. 

3 Configure Apache httpd to require and forward X.509 client certificates. 

4 Configure mod_jk to forward X.509 client certificates. 

Configure Apache httpd to Require and Forward X.509 Client Certificates 

Add the following lines to the Apache httpd configuration (for instance, to the load 

balancer’s virtual host, where the HTTPS configuration was added): 

# Configure client cert 

SSLVerifyClient require 

SSLVerifyDepth 1 

SSLUserName SSL_CLIENT_S_DN_CN 



# Configure mod_jk directives 

JkMountCopy On 

JkOptions +ForwardKeySize +ForwardSSLCertChain 

Configure mod_jk to Forward X.509 Client Certificates 

Add the following to the mod_jk configuration (typically, a file called mod_jk.conf 

included by httpd.conf or httpd-ssl.conf) 

JkEnvVar SSL_CLIENT_CERT 

You should now have a load balancer that requires and forwards X.509 Client 

Certificates. 

9.13 Running Database Preparation Scripts 

Manually 

The automatic create_databases script requires that your database engine supports 

username and password authentication. If your database for some reason does not 

support this, because, say, you are using Kerberos authentication, you must run the 

SQL preparation scripts manually. 

The scripts you need to run are: 

• create_server_db.sql 

• populate_server_db.sql 

• create_demotables.sql 

• All the SQL files in the folder demodata 

Note: Demo SQL scripts are only necessary if you want to install the demo database 

shipped with the Spotfire Server. 

Read through the create_databases script to understand how they are run. Below are 

some notes regarding the supported database server types. 

Oracle 

When populating a Spotfire database residing on an Oracle Server the 

create_databases script passes certain variables to these scripts. These variables 

include: 

• ROOTFOLDER 

• CONNECTIDENTIFIER 

• SERVER_DATA_TABLESPACE 

• SERVER_DATA_TABLESPACE 

When you run the SQL scripts manually, you must make sure to pass these variables 

along to the scripts. For example: 



sqlplus @DBServer @create_server_env.sql "spotfire_server" 


When populating a Spotfire database residing on a Microsoft SQL Server the 

create_databases script passes certain variables to these scripts. These variables 

include: 

• SERVERDB_NAME 

• DEMODB_NAME 

When you run the SQL scripts manually, you must make sure to pass these variables 

along to the scripts. For example: 

sqlcmd -S DBServer\DBInstance -i create_server_db.sql -v 

SERVERDB_NAME="spotfire_server" 

9.14 Resizing Temporary Tablespace 

The tablespaces/database files for Spotfire Server using Oracle/MSSQL Database uses 

autoextend/autogrowth by default. If this turns out to be inappropriate for your needs 

alter this settings. It might be desirable to alter the amount the files should be extended 

by with each increment. For Oracle there is a maxsize for each tablespace which 

should be reviewed. For MSSQL, there is an unlimited growth this should also be 

reviewed. 

9.15 Modifying the Virtual Memory 

 

If many simultaneous users intend to perform heavy data pivoting via Information 

Services or in other ways stress the server, you may need to modify the amount of 

memory available to the virtual machine. The application server’s JVM must have 

equal settings for the initial and maximum heap sizes, otherwise data pivoting in 

Information Services will not work properly and there might be a risk that the server 

will run out of memory. 

Note: Do not allocate too much heap memory because every JVM has a specific upper 

limit for how much memory it can handle. If the memory allocation exceeds this limit, 

the JVM may not start. The recommended setting that will work for most installations 

is the default value of 1024 MB. 

To Set Up the Start Script (not running as a Windows service): 

1 Open the file /tomcat/bin/setenv.bat/.sh in a text editor. 

2 Find the line that sets the variable JAVA_OPTS: 

set JAVA_OPTS=-server -XX:+DisableExplicitGC -XX:MaxPermSize=256M -Xms1024M -Xmx1024M 

or 



JAVA_OPTS="-server -XX:+DisableExplicitGC -XX:MaxPermSize=256M -Xms1024M -Xmx1024M" 

 

3 Alter the -xms and the -Xmx values: 

-Xms1024M -Xmx1024M 

to the amount of memory you wish to allocate. 

4 Restart the server. 

To Set Up the Windows Service (when running as a Windows service): 

1 Stop the TIBCO Spotfire Server service 

2 Go to the /tomcat/bin directory 

3 Run the command 

service.bat remove 

4 Edit the /tomcat/bin/service.bat file. 

5 Look for the entries: 

--JvmMs 1024 --JvmMx 1024 

6 Alter the “1024” to suitable memory values (in MB). 

7 Run the command 

service.bat install 

8 Start the TIBCO Spotfire Server service. 

9.16 Starting and Stopping the Spotfire Server 

Note: When you follow the instructions below, only the Spotfire Server Controller 

will start and stop. To make the servers available to clients, you need to start them in 

the configuration console. See the section “Architectural Overview” on page 6 and 

“Configure the System” on page 47 for more information. 

9.16.1 For Windows, with a Service 

 

 

To start Spotfire Server: 

Start Control Panel > Administrative Tools > Services. Find the service called 

“TIBCO Spotfire Server 3.2.2” and start it. 

To stop Spotfire Server: 

Start Control Panel > Administrative Tools > Services. Find the service called 

“TIBCO Spotfire Server 3.2.2” and stop it. 



9.16.2 For Windows, with No Service 

 

 







Comment: The controller will stop running if you close the command prompt or log 

out of the machine. 





4 Run the shutdown.bat file. 

Response: The Spotfire Server Controller stops. 

9.16.3 For Solaris, Red Hat, and SUSE with RC script 

 

 



2 Run the command /etc/init.d/tss start. (Refer to the section “For Solaris, Red Hat, and 

SUSE” on page 49 for instructions on how to install this script). 




2 Run the command /etc/init.d/tss stop. (Refer to the section “For Solaris, Red Hat, and 

SUSE” on page 49 for instructions on how to install this script). 




9.16.4 For Solaris, Red Hat, and SUSE, without RC 

script 

 

 


1 Log in as the user that installed Spotfire Server. 

2 Execute the command /tomcat/bin/startup.sh. 



1 Log in as the user that installed Spotfire Server. 

2 Execute the command /tomcat/bin/shutdown.sh. 


9.17 Data Source Templates 

9.17.1 What Are Data Source Templates? 

One feature of the Spotfire system is the ability to create "information links", which 

are easy-to-use aids for users to access data stored in databases. Using the Information 

Designer tool found in the TIBCO Spotfire client, a database administrator can 

configure which data sources should be available to choose from when creating such 

information links. 

When a connection is made to a data source it needs information about which type of 

database is used, as well as which type of database driver is used to connect to it. To 

make it easier to set up multiple data sources in Information Designer, there are a set 

of "data source templates" with predefined settings that can be used later in 

Information Designer. You can also create custom data source templates. All data 

source templates are specified in the TIBCO Spotfire Configuration Console. 

A data source template is an XML configuration. This XML configuration includes a 

number of settings that customize the way information links interact with the data 

source. Read more about the XML format in “XML Settings” on page 110. 

The following data source templates are available by default: 

• Oracle (DataDirect driver) 

• Microsoft SQL Server (DataDirect driver) 

When adding more data source templates, you can select to base these on the 

following types: 

• DB2 



• DB2 (DataDirect) 

• DB2 Type4 

• MySQL 

• MySQL5 

• MySQL (DataDirect) 

• Netezza 

• ODBC 

• Oracle 

• Oracle (DataDirect) 

• Oracle (delegated Kerberos) 

• SAS/SHARE 

• SQL Server 

• SQL Server 2005 

• SQL Server (DataDirect) 

• SQL Server (JTDS) 

• Sybase 

• Sybase (DataDirect) 

• Sybase (JTDS) 

• Teradata 

For a data source template to become available in the Information Designer, it must be 

enabled from the configuration console. For each data source template in the list, there 

is a check box that states whether the template is active or not. 

Note: For the MySQL5 native driver to work with MySQL data sources that includes 

TIMESTAMPS that can potentially be null, you have to edit the template to get it to 

work: 

Find the section that reads: 

 

 

useDynamicCharsetInfo 

false 

 

 

and add the following (within the connection-properties tag): 

 

noDatetimeStringSync 

true 

 



 

zeroDateTimeBehavior


Comment: You will be prompted to stop the entire cluster. 

Response: The list of data source templates will become editable. 

4 In the list of data source templates, click on the one you want to edit. 

Response: The Data Source Template dialog is displayed. 

5 Modify the name for your new data source template. 

6 Modify the XML settings to correspond to your intended data source and driver. You 

can copy/paste information in the edit field. 

7 Click Save. 

Response: The dialog closes and your data source template is updated in the list. 

8 Click the Done button on the toolbar. 

9 Click Start Cluster on the toolbar to restart the cluster. 

9.17.3 Enabling/Disabling a Data Source Template 

 

For a data source template to become available in the Information Designer, it must be 

enabled from the TIBCO Spotfire Configuration Console. For each data source 

template in the list, there is a check box that states whether the template is active or 

not. 

To enable/disable a data source template: 

1 Start the TIBCO Spotfire Configuration Console. 

2 Go to the Data Source Templates tab. 

3 Click the Edit button on the toolbar. 



4 In the list of data source templates, find the one you want to enable/disable. 

5 Select the check box on the corresponding row to enable the data source template, or 

deselect the check box to disable the data source template. 


Comment: If you have added a data source template that does not use the pre-installed 

DataDirect driver, you must manually install this on every Spotfire Server 

in the cluster before you restart the cluster. Download the appropriate 

driver jar file and place it in the /tomcat/ 

webapps/spotfire/WEB-INF/lib folder of every server. 




9.17.4 Removing a Data Source Template 

 

To remove a data source template: 


2 Go to the Data Source Templates tab. 




4 Click on a row to select that data source template. 

5 Click the Remove button. 

Response: The data source template is removed from the list. 



Note: Make sure that you do not have any data sources that use the data source 

template before you remove anything. If a data source template is removed, all data 

sources using that template will stop working. 

9.17.5 XML Settings 

The table below shows all settings available. Note that the only mandatory settings 

needed in the XML-file are the first four: 

• type-name 

• display-name 

• driver 

• connection-url-pattern 

If left out, all other settings will automatically use their default values. 

Setting Description Default Notes 

type-name A unique name for 

the configuration 



display-name 

driver 

The name shown 

in the Information 

Designer, Data 

Sources 

workbench 

The JDBC driver 

Java class used for 

creating 

connections 

A pattern for the 

connection URL 

ping-command A dummy 

command to test 

connections 

connectionurl-pattern 

connectionproperties 

metadataprovider 

sql-filter 

sql-runtime 

fetch-size 

JDBC connection 

properties 

Java class that 

provides database 

metadata 


generates SQL 


handles SQL 

execution 

A fetch size 

specifies the 

amount of data 

fetched with each 

database round 

trip for a query. 

The fetch size is 

measured as the 

number of fields, 

which is 

calculated to the 

number of rows 

for a particular 

query. 

SELECT 1 

BasicJDBCMetadataProvider 

BasicSQLFilter 

BasicSQLRuntime 

URL syntax is driver 

specific 

See Spotfire Technical 

Network for more info. 





10000 The specified value is 

shown as the default 

value in ID. May be 

changed at instance 

level. 



batch-size 

table-types 

max-columnname-length 

supportscatalogs 

supportsschemas 

supportsprocedures 

supportsdistinct 

supportsorder-by 

column-namepattern 

table-namepattern 

schema-namepattern 

A batch size 

specifies the 

amount of data in 

each batch update. 

The batch size is 

the number of 

fields, which is 

calculated to the 

number of 

operations for a 

particular type of 

operation. 

The maximum 

length of a 

database column 

name 

Specify which 

table types to 

retrieve 

Tells if the driver 

supports catalogs 


supports schemas 


supports stored 

procedures. 


supports distinct 

option in SQL 

queries 


supports order-by 

option in SQL 

queries. 

Determines how a 

column name is 

written in the SQL 

query. 


table name is 


query. 


schema name is 


query. 

100 The specified value is 

shown as the default 

value in ID. May be 

changed at instance 

level. 

30 This limit is used when 

creating temporary 

tables. 

TABLE, VIEW 

true 

true 

false 

true 

true 

“$$name$$” 

“$$name$$” 

“$$name$$” 



catalog-namepattern 

procedurename-pattern 

column-aliaspattern 

string-literalquote 

max-in-clausesize 

condition-listthreshold 

expand-inclause 

tableexpressionpattern 

procedureexpressionpattern 


catalog name is 


query. 


procedure name is 


query. 


column alias is 


query. 

The character 

used as quote for 

string literals 

The maximum 

size of an SQL 

IN-clause. Larger 

lists are split into 

several clauses 

that are OR:ed 

together. 

A temporary table 

is used when 

executing an SQL 

query, where total 

size of a condition 

list is larger than 

this threshold 

value. 

If true, an SQL 

IN-clause will be 

expanded into OR 

conditions. 


table expression is 


query. 


procedure 

expression is 


query. 

“$$name$$” 

“$$name$$” 

“$$name$$” 

1000 

SQL-92 standard 

10000 Depends on the 

maximum SQL query 

size. 

false 

[$$catalog$$.][$$schema$$.]$$table$$ 

[$$catalog$$.][$$schema$$.]$$procedure$$ 

catalog and schema 

may be optional 

(surrounded by 

brackets) 



date-literalformatexpression 

time-formatexpression 

time-literalformatexpression 

date-timeformatexpression 

Integer 

representing the 

jdbc type 

identifying a table 

returned form a 

procedure as 

defined by 

java.sql.Types. 

proceduretable-jdbc-type 

proceduretable-typename 

date-formatexpression 

Display name for 

tables from 

procedure. 

An expression that 

converts a date 

field to a string 

value on the 

format: 

"YYYY-MM- 

DD", e.g., "2002- 

11-19" 


converts a date 

literal on the 

format "YYYY- 

MM-DD" to a 

date field value. 


converts a time 

field to a string 

value on the 

format: 

"HH:MM:SS", 

e.g., "14:59:00" 


converts a time 


format 

"HH:MM:SS" to a 

time field value. 


converts a 

datetime field to 

string value on the 

format: "YYYY- 

MM-DD 

HH:MM:SS", e.g. 

"2002-11-19 

14:59:00" 

0 

null 

$$value$$ 

'$$value$$' 

$$value$$ 

'$$value$$' 

$$value$$ 

This is currently not 

visible to the user in 

any UI. 

Used in WHERE and 

HAVING clauses. 

The tag $$value$$ is a 

placeholder for the date 

field. 




placeholder for the date 

literal. 




placeholder for the time 

field. 




placeholder for the time 

literal. 




placeholder for the 

date-time field. 



date-timeliteral-formatexpression 


converts a datetime 


format "YYYY- 

MM-DD 

HH:MM:SS" to a 

date-time field 

value. 

'$$value$$' 




placeholder for the 

date-time literal. 

java-to-sqltypeconversions: 

String 

Integer 

Long 

Float 

Double 

Date 

Time 

DateTime 

Type conversions 

needed when a 

join data source 

creates a 

temporary table 

for result from a 

subquery. 

For String 

conversion %s 

will be replaced 

by the size of the 

string. 

A match-lengthí 

attribute may be 

specified (see 

MySQL). 

VARCHAR($$value$$) 

VARCHAR(255) 

INTEGER 

BIGINT 

REAL 

DOUBLE PRECISION 

DATE 

TIME 

TIMESTAMP 

Different String types 

may be needed 

dependant of the length 

of the string. 

Note that there must be 

a VARCHAR 

conversion for when the 

length of the string is 

unknown (255 in the 

example here). 

When several 

VARCHAR mappings 

are specified, the 

mapping that first 

matches the ëmatchlengthí 

is used. 

temp-tablename-pattern 

Determines how 

to format a 

temporary table 

name in an SQL 

command. 

$$name$$ 



create-temptablecommand 

drop-temptablecommand 

data-sourceauthentication 

lob-threshold 

SQL commands 

for creating a 

temporary table. 

This is used to 

store filter values 

(when more than 

'condition-listthreshold') 

and to 

store result from 

subqueries. 

$$name$$ is a 

placeholder for 

the table name. 

$$column_list$$ 

is a placeholder 

for a column list 

on the format 

"(name type, 

name type, ...)" 

SQL commands 

for deleting a 

temporary table. 

$$name$$ is a 

placeholder for 

the table name. 

Default value data 

source 

authentication. 

(boolean). 

Threshold when 

LOB values used 

as parameters in a 

WHERE clause, 

must be written in 

temporary tables 

CREATE TEMPORARY TABLE $$name$$ 

$$column_list$$ 

DROP TABLE $$name$$ 

The syntax may vary 

between databases. 

The syntax may vary 

between databases. 

false 

This value can be set 

(overridden) in the 

Information Interaction 

Designer. 

-1 The default (-1) means 

no limit. 



 

oracle 

Oracle 

oracle.jdbc.OracleDriver 

jdbc:oracle:thin:@<host>:<port1521>:<sid> 

use-ansii-styleouter-join 

credentialstimeout 

The default 

generated SQL 

uses the Oracle 

way with “(+)” to 

indicate joins. If 

this setting is sett 

to true an attempt 

is made to rewrite 

it to standard 

ANSII format, 

making it possible 

to run on non 

Oracle databases 

Defines the time 

in seconds user 

credentials are 

cached on the 

server for a 

particular data 

source. Value 

must be between 

900 (15 minutes) 

and 604800 (1 

week). 

false 

86400 (24 hours) Applicable only if datasource-authentication 

is 

set to true. 

9.17.5.1 Defining JDBC Connection Properties 

The optional parameter block in the 

configuration can be used to define JDBC connection properties parameters to be used 

when connecting to the data sources of the given type. A typical use case for this 

feature is to specify encryption and integrity checksum algorithms for secure database 

connections. 

Each connection property consists of a key-value pair. The syntax for specifying 

JDBC connection properties for a connection pool is shown in the configuration 

example below. 

If you need different JDBC connection properties for different data sources of the 

same type, just duplicate the configuration, rename the 

configurations for each variant needed and define the proper JDBC connection 

properties. Make sure to update any already existing data sources so that they are of 

the correct type. 

Example: Defining JDBC Connection Properties for data source of type "oracle": 



SELECT 1 FROM DUAL 

 

 

oracle.net.encryption_client 

REQUIRED 

 

 

oracle.net.encryption_types_client 

( 3DES168 ) 

 

 

oracle.net.crypto_checksum_client 

REQUIRED 

 

 

oracle.net.crypto_checksum_types_client 

( MD5 ) 

 

 

... 

 

9.17.5.2 Advanced Connection Pool Configuration 

Beginning with TIBCO Spotfire Analytics Server 10.1, a new type of connection pool 

is used for the data sources in Information Services. The new connection pool was 

introduced for the user directory and other components from version 9.0. Those 

components retrieve their database configurations from the META-INF/database.xml 

file, but the configuration templates for the data sources in Information Services still 

reside in the datasource template set up in the configuration console. 

Not all configuration parameters that appear in the META-INF/database.xml file are 

supported for data sources in Information Services, but the following special 

parameters are available: 

• "spotfire.pooling.data.source.scheme" 

(corresponds to the “pooling-scheme” parameter in the meta-inf/database.xml 

configuration file. 

• "spotfire.pooling.data.source.connection.timeout" 

(corresponds to the “connection-timeout” parameter) 

• "spotfire.pooling.data.source.login.timeout" 

(corresponds to the “login-timeout” parameter). 

• "spotfire.kerberos.login.context" 

(corresponds to the “kerberos-login-context” parameter) 

It is also possible to revert to the old type of connection pool by setting the 

"spotfire.connection.pool.factory.data.source" parameter to 

"init.commands.data.source". The default value for this parameter is 

"pooling.data.source". 

All these parameters should be added as JDBC connection properties. However, they 

will never be used as real JDBC connection properties and will never be sent to a 

database server. 



Example: Configuring a PoolingDataSource for Oracle databases 

 

oracle 

Oracle 




 

 

spotfire.pooling.data.source.scheme 

WAIT_ADAPTIVE 

 

 

spotfire.pooling.data.source.connection.timeout 

1800 

 

 

spotfire.pooling.data.source.login.timeout 

30 

 

 

... 

 

9.17.5.3 Using Kerberos Authentication for JDBC Data Sources 

Configuration of Kerberos authentication for JDBC data source is performed in a 

similar way to the data sources in data-sources.xml. See also the TIBCO Spotfire 

Server - Installation and Configuration Manual for more information about how to set 

up Kerberos authentication with the Spotfire database, which works in a similar 

fashion. 

Example: Configuring a PoolingDataSource for Oracle databases 

 

oracle 

Oracle 




 

 

spotfire.kerberos.login.context 


 

 

oracle.net.authentication_services 

( KERBEROS5 ) 

 

 

... 

 



9.17.5.4 Using Kerberos Authentication with Delegated 

Credentials 

Before configuring JDBC Data Sources for Kerberos authentication with delegated 

credentials, it must be verified that it is possible for clients to connect to the Spotfire 

Server using Kerberos authentication. When the server is correctly set up and 

everything works, it is time to proceed to the next step. 

To set up Information Services to use delegated Kerberos credentials when making 

connections to database servers, the Spotfire Server’s service account used for 

retrieving the ticket-granting ticket (TGT) must be given the permission to delegate 

client credentials. In the “Active Directory Users and Computers” control panel on the 

domain controller, the “Account” tab of the properties dialog for the service account 

contains an “Account is trusted for delegation” check box that can be checked to give 

the service account that permission. 

After setting up the service account’s delegation rights, a new JDBC Data Source must 

be created in the data source template xml. Copy a non-Kerberos definition for the 

same type of data source and add the special JDBC connection property 

“spotfire.connection.pool.factory.data.source” with the value “kerberos.data.source”. 

All JDBC connection properties required to configure the JDBC driver for Kerberos 

authentication should also be added. Please consult your database server’s 

documentation for more information about configuring the JDBC driver. 

Example: Setting up Kerberos authentication with delegated credentials for an Oracle 

database 

 

oracle-kerberos 

Oracle Kerberos 




 

 

spotfire.connection.pool.factory.data.source 

kerberos.data.source 

 

 

oracle.net.authentication_services 

(KERBEROS5) 

 

 

... 

 

9.17.5.5 Verifying a Data Source Template 

To verify the data source template from TIBCO Spotfire: 



1 Log into TIBCO Spotfire as an administrator. 

2 Select Tools > Create Information Link.... 

3 Click on the Setup Data Source link. 

4 Enter a name for the data source connection. 

5 Specify the type of data source. 

6 Enter the connection URL. 

7 Enter max/min-values for the connection pool. 

8 Enter a username and a password to connect to the database. 

9 Click Save. 

10 Click on the Data sources tab in the left pane. 

Response: The data source name should appear in the tree to the left, ready for use. 

9.18 Default Join Database 

9.18.1 What is Default Join Database? 

The default join database is used for creating temporary tables and joining the final 

result when running an information link. Most often using the standard Spotfire 

database for the default join database will work fine. However, in certain situations 

you may want to configure another database to be used. For example, if you prefer to 

run these operations as a specific user on the database, or if you want to use a database 

that is specifically optimized for temporary tables. 

To set up Default Join Database, start the TIBCO Spotfire Configuration Console, and 

go to the Default Join Database tab. Make the appropriate settings there. 

Default Join Database Settings 

Option 

Configure Custom Default 

Join Database 

Type 

Connection URL 

Description 

Sets whether you want to configure a Custom Default 

Join Database (Yes) or use the standard Spotfire 

database (No). 

Sets the type of database and driver you want to use as 

the default join database. 

This is the connection URL to the database. 



Number of Connections 


Sets a minimum and maximum Number of 

Connections to use when accessing the database. 

Sets the Username and Password that will be used to 

access the database. 

Test Connection 

Click the Test Connection button to verify that the 

provided information can be used to connect to the 

database. 

9.19 Login Behavior 

9.19.1 What is Login Behavior? 

When users start their TIBCO Spotfire clients you can decide how login should work. 

You can configure: 

• If the login dialog should be displayed or not. 

• If users should be allowed to work offline or if they must always log in. 

• If users can select “Save my login information” in the login dialog and store the 

login information for future automatic login. 

• If users should be forced to log in after working offline for a certain number of 

days. 

• If you want an RSS feed to be shown in the login dialog. 

The TIBCO Spotfire login dialog 



9.19.2 Configuring Login Behavior 

 

To configure login behavior: 


2 Go to the Login Behavior tab. 



Response: The Client Behavior fields will become editable. 

4 Set Login dialog display behavior. 

• Always (show dialog even if user has chosen Save my login information) 

• Never (never show dialog) 

• Standard (only show dialog if user has not chosen Save my login information) 

5 Set Allow Work offline. 

• Yes - users can work offline if they like. 

• No - users must always be logged in to the TIBCO Spotfire Server to run TIBCO 

Spotfire. 

6 Set Allow Save my login information. 

• Yes - users can select to store the login information for future automatic login. 

• No - users must always provide user name and password when logging in. 

7 Set Work offline limit. 

• Do Not Set Limit - the users can select to Work Offline and will never be forced 

to connect to the TIBCO Spotfire Server. 

• Set days client can operate without connecting to server - users can select to 

Work Offline but will be prompted and forced to log in after # number of days. 



9.19.3 Configuring RSS Feed 

It is possible to configure the TIBCO Spotfire Server to show messages in the login 

dialog for the end users. For example, news of upcoming scheduled maintenance of 

the TIBCO Spotfire Server could be shown. 

One option is to specify a path to an rss.xml file located on an TIBCO Spotfire Server, 

which you can update manually with news. Another is to specify the URL to an 



 

external RSS feed. Regardless, you must make sure the specified rss-feed complies 

with the standard RSS 2.0 specification, and that the source is available to the end 

users’ clients. Note that HTML in the RSS feed is not supported. 

If you want to make sure all users see the news in the login dialog, you can set the 

Display behavior setting to “Always”. This means the login dialog will be shown to all 

users regardless of whether they have opted to save their login credentials for 

automatic login. 

To configure RSS feed: 


2 Go to the Login Behavior tab. 



Response: The Client Behavior fields will become editable. 

4 In the RSS Feed field, enter a URL to the RSS feed you want to use. 

Comment: If you want to remove an RSS feed, just clear the input field. 



Below is an example of an RSS 2.0 compliant RSS file: 

 

 

 

TIBCO Spotfire Server News 

http://myserver/spotfire/rss 

My description goes here. 

en-us 

Wed, 03 Jan 2007 04:00:00 GMT 

Mon, 12 Feb 2007 09:41:01 GMT 

http://myserver/spotfire/rss 

Weblog Editor 2.0 

editor@example.com 

webmaster@example.com 

 

Server down for maintenance 2008-03-03 

http://sharepoint/news/item1.aspx 

 

Mon, 12 Feb 2007 09:39:21 GMT 

123456 

 

 

Remember to save your work before going home 

http://internal/department/test 



Servers will be down this weekend. 

Mon, 08 Jan 2007 11:06:42 GMT 

123455 

 

 

 

9.20 Impersonation 

What Is Impersonation? 

When the cluster of TIBCO Spotfire Servers is used in conjunction with one or more 

TIBCO Spotfire Web Player servers, which have been configured for certain 

authentication methods, for example, NTLM, impersonation also needs to be enabled 

on the TIBCO Spotfire Servers for seamless login. 

Impersonation means that the TIBCO Spotfire Web Player is responsible for 

authenticating users. Calls from the TIBCO Spotfire Web Player to the TIBCO 

Spotfire Server cluster will be made on behalf of the person authenticated. 

For example, consider that the TIBCO Spotfire Web Player server is configured for 

certificate authentication. This authentication method is done on the https network 

level and there is no user name or password which can be conveyed to the TIBCO 

Spotfire Server cluster for login. Instead the TIBCO Spotfire Web Player server is 

trusted for impersonation. The TIBCO Spotfire Web Player server is allowed to make 

calls on behalf of any user without the ordinary authentication mechanism. This means 

the user will see his/her specific files in the library etc. 

Enabling impersonation can pose a potential security issue, which is why this is 

disabled by default. To strengthen security there are a number of requirements that can 

be imposed on a call in order for it to be allowed to impersonate. 

9.20.1 Enabling Impersonation 

To enable impersonation, you need to activate it from the TIBCO Spotfire 

Configuration Console. There are a number of requirements that you can set up which 

decides when to allow impersonation. These requirements are on the impersonate call 

from a TIBCO Spotfire Web Player server to the TIBCO Spotfire Server cluster. All 

the requirements you decide to set up must be met for the impersonation call to be 

allowed. 

If you want to require the impersonation call to be made on https, check the Require 

SSL option. If you leave it blank, both http and https are allowed. 

The call from a TIBCO Spotfire Web Player server to the TIBCO Spotfire Server 

cluster will always require authentication. This is most often done as a certain user 

which has been specified in the configuration of the TIBCO Spotfire Web Player 

server. The TIBCO Spotfire Server cluster can be configured to only allow certain 

users to be able to issue impersonation calls - typically the very user specified in the 

TIBCO Spotfire Web Player server configuration. 



 

For the TIBCO Spotfire Server cluster this is specified in the Allowed Users field(s). 

You can add as many users as you like. If you do not specify any users, then any 

authenticated user can issue impersonate calls. The most common use is to specify the 

same user as previously configured on the TIBCO Spotfire Web Player server. See the 

"TIBCO Spotfire Web Player - Installation and Configuration Manual" for more 

information. 

Specific requirements can also be made on the origin of an impersonate call. Typically, 

you would want to configure the TIBCO Spotfire Server cluster to only allow 

impersonation calls originating from the machines running a trusted TIBCO Spotfire 

Web Player server. 

If one or more servers are listed in the Web Player Server field(s), then only calls 

originating from these machines are allowed. Allowed machines can be specified in 

two ways: originating IP number or originating name. The originating IP number 

should be the IP number of the machine, and a specified originating name is resolved 

to one (or more) IP numbers using DNS. Only calls originating from one of the 

mentioned machines are valid for impersonation. If no information is provided in the 

Web Player Server field, then calls originating from any machine are valid for 

impersonation. 

To enable impersonation: 


2 Go to the Impersonation tab. 

3 Click the Edit button in the toolbar. 


Response: The Enable Impersonation drop-down list will become active. 

4 Click on the Enable Impersonation drop-down, and select Yes. 

Response: The impersonation settings become editable. 

5 Select whether you want to require the impersonation call to be made on https by 

checking the Require SSL option. If you leave it blank both http and https are 

allowed. If you select https then you must make sure both the TIBCO Spotfire Server 

and the TIBCO Spotfire Web Player server can communicate using https. 

6 Specify whether only certain users should be able to issue impersonation calls by 

entering those user names in the Allowed Users field. Only enter one user per row. 

Click the plus sign next to the field to add another row where you can specify an 

additional user. 

7 Specify whether the TIBCO Spotfire Server cluster should only accept impersonation 

calls from certain machines. If you want to limit impersonation calls in this way, 

specify the originating machine by entering the IP numer or host name in the Web 

Player Servers field. Only enter one machine per row. Click the plus sign next to the 

field to add another row where you can specify an additional machine. 

8 Click the Done button in the toolbar. 



9 Click Start Cluster in the toolbar to restart the cluster. 


Backup and Restore 

10 Backup and Restore 

10.1 Overview 

To ensure quick and easy recovery after a crash or disaster in your Spotfire system, it 

is important that you back up information stored in the system. This information 

includes user files, configuration, etc. Most of this is stored in the Spotfire Database, 

but some of it is stored on the Spotfire Server(s) and The Spotfire Web Player server. 

This manual will not describe how to perform backups, only what to back up. It is 

assumed that you have some sort of backup software for files and computers, and that 

you use the backup tools provided by your database vendor. Refer to their 

documentation for instructions on how to perform backups. 

10.2 Spotfire Database 

The most important part of the Spotfire system to back up is the Spotfire Database. 

This is where most of the user data and configuration is stored, and even if you do not 

have valid backups of other components of the Spotfire system, you will be able to 

restore functionality after a crash if the database is backed up. It is therefore vital that 

you have a valid and current backup of the Spotfire Database. 

10.3 Spotfire Server(s) 

Stored on the Spotfire Server(s) is configuration that is unique to each Spotfire Server 

in the cluster, such as authentication information regarding NTLM, Kerberos, Client 

Certificates, etc. Even if you lose this data, you will be able to get a Spotfire system 

back after a crash, by installing a new server and adding it to the cluster. For simple 

systems, where no or very little configuration is performed, this may even be enough. 

If you have made any configuration changes, however, such as listening ports, 

authentication, user directory, etc, you probably want to ensure that you have a valid 

backup of your Spotfire Server(s). Configuration stored on the Spotfire Server(s) 

includes the following: 

• Listening ports configuration (see the section “Run Installer” on page 23 and 

“Server.xml” on page 135 for more information about this) 

• Information about how to connect to the Spotfire Database (see the section 

“Database Connection Configuration” on page 138 for more information about 

this) 

• Logging configuration (see the section “Changing the Default Log Level of the 

Spotfire Server” on page 132 for more information about this) 

• Memory configuration (see the section “Modifying the Virtual Memory” on 

page 103 for more information about this) 



• HTTPS (see the section “Setting up HTTPS on a Spotfire Server” on page 86 for 

more information about this) 

• Authentication such as Kerberos, NTLM, or Client Certificates (see the section 

“Authentication and User Directory” on page 65 for more information about 

this). 

• Shared Disk. In a cluster of more than one server, you may want to configure the 

location of the Shared Disk (see the section “Shared Disk Location in a 

Clustered Environment” on page 100 for more information about this). 

• Configuration regarding data sources. Each Spotfire Server needs configuration 

regarding database drivers etc for external data sources. 

• Any other advanced configuration performed in “Advanced Procedures” on 

page 84. When performing advanced configuration, you should always take 

backup into consideration. 

To back up your Spotfire Server(s), you should select one of the following methods: 

• Back up the entire machine that Spotfire Server is running on. 

• Back up only the files that Spotfire Server installs on the machine. 

There are of course advantages and drawbacks with whichever method you select. If 

you back up the entire machine, you will be certain that no files are missing in your 

backup. On the other hand, you also have a backup that includes an entire computer 

with potentially other software running on it, that you may not want to restore after a 

crash. If you run only Spotfire Server on the machine, this is probably what you should 

choose. 

If you back up only the files that the Spotfire Server installs in the , you will potentially have a backup that is more easy to move between 

machines. You should however take special notice to back up anything you may have 

stored or configured outside the Spotfire Server installation directory. A typical 

example of this would be database drivers necessary to connect to Information 

Sources, set up in the Control Panel if running on Windows. Backing up the entire 

machine would back up these dependencies as well. Also, if you are running Spotfire 

Server on Windows, you will lose the Start Menu shortcuts and the unistall feature in 

the Control Panel when restoring this type of backup. 

For both methods, you should also consider that authentication such as Kerberos and 

Client Certificates could be difficult to restore, due to the fact that their configuration 

is tied to the specific hardware they are installed on. If you restore a backup to a 

machine different from the original one, you will probably have to set up 

authentication anew. 

Note that it is not possible to restore a backup of a Spotfire Server to a machine with a 

different operating system than the original one. 

For other components in the Spotfire system, such as the Spotfire Web Player, refer to 

their installation manuals for instructions on how to perform backups of them. 

If you have more than one Spotfire Server in the cluster, and they are configured 

differently, remember to perform backups of each server. 



To Restore a Spotfire Server 

Note: To perform a restore of a backup, you must restore to the same OS architecture 

the backup is from. If this is not possible, you must reinstall the Spotfire Server using 

the installer. 

It is recommended that you also restore a Spotfire Server to a machine with the same 

IP adddress and hostname as the old one. This will ensure that any network issues, 

such as firewall settings etc, will work smoothly after a restore. Overall, you may want 

to try to create the restored system as similar as possible to the old one, for similar 

reasons. 

Below is a step-by-step instruction for restoring Spotfire Server software. 

1 Restore the backup of to the same physical path on the 

machine as on the old. 

2 If running on Windows and starting the Spotfire Server using a Windows Service, run 

the script 

/tomcat/bin/service.bat install 

See the section “For Windows, with Windows Service” on page 48 for more 

information about the Windows Service. 

3 If running or Solaris, Redhat, or SuSe, and starting the Spotfire Server automatically 

after reboot, run the script 

/tomcat/install_startup_script.sh 

or copy the script tss to the right place. See the section “For Solaris, Red Hat, and 

SUSE” on page 49 for more information about this. 

If you are using any authentication such as Kerberos or Client Certificates, you may 

also have to set up this anew. 

10.4 Disaster Recovery 

In the event of a disaster, where you have no valid backups available, you should think 

of the following: 

• Without a valid backup of the Spotfire Database, you will not be available to 

restore your Spotfire system to its previous state. You must therefore have a 

valid and current backup of your Spotfire Database. 

• Without a valid backup of the Spotfire Server(s), you can restore your Spotfire 

system to its previous state by installing a new Spotfire Server, adding it to the 

cluster (stored in the database), and configuring it anew. 


Technical Reference 

11 Technical Reference 

11.1 Server Logs and Diagnostics 

For each TIBCO Spotfire Server you can view logs and diagnostics in the Server Logs 

and Diagnostics tool, available at the URL http://spotfireserver:80/spotfire. 

Replace spotfireserver with the name of the Spotfire Server. 

Log in with a user that has either Spotfire Administrator or Spotfire Diagnostics 

Administrator permissions. For more information about Spotfire permissions and 

administrator roles, see the TIBCO Spotfire Deploy and Administration Manual. 

Server Logs will provide detailed information about what is happening on the server, 

such as access logs, SOAP communication, Information Links that are used, etc. 

Diagnostics will provide information about the server itself, such as information about 

the Database Server, Operating System, TIBCO Spotfire Server, Cluster 

Configuration, Application Server, System, and Java version. 

11.1.1 Logging Overview 

The main purpose of logging is to aid in the detection, diagnosis and resolution of any 

problems the server experiences. Therefore, in the normal operation of the server, a 

very minimal amount of logging is enabled. 

11.1.2 Log Configuration Files 

You can determine what should be logged in the log files by applying settings in a 

certain Log Configuration File. This configuration file will set the level of detail for 

the actual log files. To do this, first select the Log File, then select the Log 

Configuration File you want to set for the log, and then click the Set Configuration 

button. 

There are six "levels" of logging you can choose between by selecting different Log 

Configuration Files: 

• log4j-minimal.properties - The Server Log will only log errors, and the SQL 

Log will be deactivated. 

• log4j.properties - The default setting. The Server Log will log warnings, errors 

and basic information. The SQL Log will log basic SQL information. 

• log4j-debug.properties - The Server Log will log detailed debug information as 

well as warnings, errors and other detailed information. The SQL Log will log 

more detailed SQL information. 

• log4j-debug-soap.properties - The Server Log will log detailed SOAP 

information in addition to all the debug information from log4jdebug.properties. 



• log4j-trace.properties - This Server Log will log extremely low-level debug 

information including all the debug information from log4j-debug.properties. 

• log4j-trace-soap.properties - This Server Log will log extremely low-level 

SOAP information including all the debug information from log4jtrace.properties. 

Note: If you wish to limit the number of choices of log configurations available in the 

Server Logs and Diagnostics tool, you can move or remove these files from the 

/tomcat/webapps/META-INF directory. 

Warning: Do not use the "Debug", "Debug with SOAP" "Trace" or "Trace with 

SOAP" modes for continuous server use, since doing so decreases the performance of 

the server, and also produces very large log files. 

If you want to configure the logs in other ways than the above options allow, you can 

create your own Log Configuration File using standard Log4j syntax (more 

information can be found at http://logging.apache.org/log4j/docs/ 

documentation.html). 

Placing a new log4j configuration file with the name matching the pattern 

log4j*.properties in the /tomcat/webapps/META-INF 

directory, will cause it to appear in the drop-down list among the other Log 

Configuration Files and can thus be selected. 

Note: When you restart the server, the Log Configuration File will revert to the default 

selection. To set the default log level, see the instructions below. 

11.1.3 Changing the Default Log Level of the Spotfire 

Server 

To change the default log level of the Spotfire Server, you need to manually edit a 

configuration file located on each server. 

 

To Change the Default Log Level of the Spotfire Server 

1 Open the file /tomcat/webapps/spotfire/WEB-INF/ 

web.xml in a text or xml editor. 

2 Look for the param-name com.spotfire.logging.config.file. 

3 Change the param-name to one one of the log configuration files described above. 

4 Restart the Spotfire Server. 

To change the default log level of the Configuration Console, edit the file /tomcat/webapps/admin/WEB-INF/web.xml instead. 

To change the default log level of the Spotfire Controller, edit the file /tomcat/webapps/controller/WEB-INF/web.xml instead. 



11.1.4 Console Debugging: 

All levels of logging are also available in "Console Debugging" versions: 

• log4j-minimal-with-console.properties 

• log4j-with-console.properties 

• log4j-debug-with-console.properties 

• log4j-debug-soap-with-console.properties 

• log4j-trace-with-console.properties 

• log4j-trace-soap-with-console.properties 

These should only be used temporarily when running the server in console mode. This 

will provide real-time logging in a console window. 

Do NOT use these while running the Spotfire Server as a Windows service, since this 

may rapidly create huge log files. 

11.1.5 Log Files 

TIBCO Spotfire Server uses rolling logs, which means that when a log file gets too big 

it splits into several files. These are indexed by a number, (the higher the number, the 

older the log) and can be selected in the drop-down list in the Server Log Files 

interface. When a rolled log file reaches a certain number it is deleted. 

The log files are located in the /tomcat/logs/spotfire, 

/tomcat/logs/admin, and /tomcat/logs/ 

controller directories. 

There are several log files that you can configure and view: 

Server Log 

SQL Log 

SOAP Log 

Actual file located in /tomcat/logs/spotfire/ 

dss.log. 

This file logs all activity on the server except the events recorded in the 

Server Access Log. It includes the SQL log and a simplified version of 

the Server Access log. You can set the detail level of what this file logs by 

selecting different Log Configuration Files. 

Actual file located in /tomcat/logs/spotfire/ 

sql.log. 

This file logs the SQL that is generated each time a user executes an 

information link. You can set the detail level of what this file logs by 

selecting different Log Configuration File. 

This log stores information about the SOAP communication on the 

server. 



Server Diagnostics 

Log 

Actual file located in /tomcat/logs/spotfire/serverdiagnostics.log 

This log is always enabled and contains diagnostic information collected 

during server startup. It shows whether or not the server could be started 

successfully and other vital information collected from various parts of 

the server. This log is always enabled and unaffected by Log 

Configuration File settings. 

Server Access Log Actual file located in /tomcat/logs/spotfire/ 

access.log 

This log is always enabled and contains all access attempts to the TIBCO 

Spotfire Server. It shows which user has accessed what files on the server, 

when the access took place, and whether or not the access was granted. It 

uses standard "W3C common logfile format". 

Server Usage Log Actual file located in /tomcat/logs/spotfire/ 

usage.log. 

This file is a lighter alternative to the server access log described above as 

it does not contain information regarding the file accessed. Apart from 

that, the two files contain the same information. This log is always 

enabled and unaffected by Log Configuration File settings. 

dss-cxf.log This file logs the CXF SOAP tool from Apache. 

isusage.log Actual file located in /tomcat/logs/spotfire/ 

isusage.log. 

This log file contains information about what user accesses which 

Information Link and when. 

library.log Actual file located in /tomcat/logs/spotfire/ 

library.log. 

This log file logs whenever a user stores, opens or deletes a file from the 

library. 

impex.log This file logs library import and export. 

Tomcat StdOut This file cannot be viewed in the UI, you must open the actual log file. 

Log 

Actual file located in 

/tomcat/logs/spotfire/stdout_yyyyMM dd.log, 

where yyyyMMdd is replaced by the log file’s creation date. 

The Tomcat application server redirects all output to StdOut to this log 

file. Note: By default, this log file is not rolled. 

Tomcat StdErr Log This file cannot be viewed in the UI, you must open the actual log file. 


/tomcat/logs/spotfire/stderr_yyyyMMdd.log, 

where yyyyMMdd is replaced by the log file’s creation date. 

The Tomcat application server redirects all output to StdErr to this log 

file. Note: By default, this log file is not rolled. 



Jakarta Service 

Log 

This file cannot be viewed in the UI, you must open the actual log file. 


/tomcat/logs/spotfire/jakarta_service_yyyyMM 

dd.log, where yyyyMMdd is replaced by the log file’s creation date. 

This log file contains information about when the Tomcat service is 

started and stopped. 

11.1.6 Export Log File 

By clicking on the Export Log File button, you can save the current log file to disk. 

Note: This only exports the Spotfire Server log, not the logs of the Configuration and 

Console and Spotfire Controller. 

11.1.7 Log Out 

For security reasons, always make sure to exit your browser when logging out of 

Server Logs and Diagnostics. This makes sure no session cookies are retained. 

11.2 Server.xml 

Spotfire Server is implemented as a Tomcat web application. For this reason, it uses a 

standard Tomcat web application configuration file, server.xml, to store information it 

needs when starting. This file is stored in /tomcat/conf/>. You 

should only need to make changes to this server if you need to change port numbers 

after installation, or if you need to tweak Tomcat behavior. Note that each Spotfire 

Server in a cluster has a server.xml. Therefore, if you need to make changes to it, you 

need to make those changes to all the servers in the cluster. 

The standard server.xml delivered with Spotfire Server looks like this: 

 

 

 

 

 


unpackWARs="false" autoDeploy="false" 

xmlValidation="false" xmlNamespaceAware="false" 

deployOnStartup="false"> 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 



 

 

 

 

Note: The variables [SpotfirePort], [MCPort], and [ControllerPort] are set by 

selections made in the Spotfire Server installer. The variables [ServerHostname]-srv 

and [ServerHostname]-adm are automatically set by the installer by adding the strings 

“-srv” and “-adm” to the server’s hostname. Also note that these variables must not 

have any characters that could potentially need “escaping”, such as “.” (for instance 

spotfireserver1.company.com). 

For detailed information about the server.xml syntax, see the Apache Tomcat 

documentation located at http://tomcat.apache.org/ 

11.3 krb5.conf 

This file contains settings for Kerberos. Listed below is an unmodified version of the 

file, as it is shipped, and also a version with example values filled in. 

[libdefaults] 

default_realm = MYDOMAIN 

default_keytab_name = spotfire.keytab 

default_tkt_enctypes = rc4-hmac 

default_tgs_enctypes = rc4-hmac 

[realms] 

MYDOMAIN = { 

kdc = mydc.mydomain 

admin_server = mydc.mydomain 

default_domain = mydomain 

} 

[domain_realm] 

.mydomain = MYDOMAIN 

mydomain = MYDOMAIN 

[appdefaults] 

autologin = true 

forward = true 

forwardable = true 

encrypt = true 

[libdefaults] 

default_realm = RESEARCH.EXAMPLE.COM 

default_keytab_name = spotfire.keytab 

default_tkt_enctypes = rc4-hmac 

default_tgs_enctypes = rc4-hmac 

[realms] 

RESEARCH.EXAMPLE.COM = { 

kdc = example-dc.research.example.com 

admin_server = example-dc.research.example.com 

default_domain = research.example.com 

} 



[domain_realm] 

.research.example.com = RESEARCH.EXAMPLE.COM 

research.example.com = RESEARCH.EXAMPLE.COM 

[appdefaults] 

autologin = true 

forward = true 

forwardable = true 

encrypt = true 

11.4 Database Connection Configuration 

The Spotfire database, discussed previously in this manual, holds information 

important to the Spotfire Servers. When logging into the configuration console for the 

first time, a prompt will appear asking for a valid URL to the database. The 

information entered here is stored by the configuration console and then distributed to 

each server added to the cluster. See the section “Starting the Configuration Console” 

on page 50 for more information about this. 

If the connection information of the database changes for some reason, you need to 

reconfigure the Spotfire Servers and the configuration console so that they are able to 

connect to the database. For the configuration console, you must edit the file 

connections.xml, found in the /tomcat/webapps/admin/WEB-INF/ 

directory on the machine running the configuration console. For the Spotfire Servers, 

you can either remove them from the cluster and re-add them, or edit the file 

database.xml, found in the tomcat/webapps/META-INF/ directory 

on each Spotfire Server. Below is a description of how these files look. 

connections.xml 

 


 

0 


[DriverClass] 

[DBServerURL] 

false 

WAIT_CONSERVATIVE 

-1 

0 

600 

false 

true 

 

 

 

 

The strings [DriverClass] and [DBServerURL] will be automatically set to 

appropriate values by the configuration console when you add a server to a cluster. 

You can also change the string tibcosoftwareinc.jdbc.sqlserver.SQLServerDriver if 

you intend to use a different database driver. See the section “Database Drivers” on 



page 47 for more information about this. Different database drivers might offer 

different options to include in the URL. 

database.xml 

 

 

 

 

base64 

true 

 

 

key 

52b896a2-3d9b-4de1-9249-2eeee4276f35 

 

 

com.spotfire.util.transform.DESedeCredentialTransform 

 

 


 

0 


[DriverClass] 

[DBServerURL] 

[DBUserName] 

[DBPassword] 

false 

WAIT_CONSERVATIVE 

20 

5 

600 

false 

true 

 

 

 

MaxPooledStatements 

20 

 

 

 

 

 

The strings [DriverClass], [DBServerURL], [DBUserName], and [DBPassword] will 

be automatically set to appropriate values by the configuration console when you add 

a server to a cluster. If you need to change database driver or URL, see examples 

below. 

Note: The [DBPassword] will be encrypted in this file. 

Driver Class Definition Examples 

The driver class definition looks different depending on which database driver is in 

use. It must be added to each definition in each configuration file 

described above. These are the different types supported by Spotfire Server: 



Oracle (DataDirect Driver) 

tibcosoftwareinc.jdbc.oracle.OracleDriver 

Oracle (Native Driver, ojdbc6.jar) 


Microsoft SQL Server (DataDirect Driver) 

tibcosoftwareinc.jdbc.sqlserver.SQLServerDriver 

Microsoft SQL Server(Native Driver, sqljdbc4.jar) 

com.microsoft.sqlserver.jdbc.SQLServerDriver 

jTDS (Native Driver, jtds.jar) 

net.sourceforge.jtds.jdbc.Driver 

Database Connection URL Components and Examples 

Component 

API 

Database Driver 


Hostname 

Port 

Database Name or SID 

Options 

Description 

Specifies which API to use. This is always jdbc. 

Specifies which database driver to use to connect to the 

database. Default tibcospotfireinc, which will use the 

Spotfire Datadirect driver. If you have installed a different 

driver, you may provide this here. 

Specifies the type of database server. Either sqlserver or 

oracle. 

Note: Server Type is only applicable when using the 

DataDirect driver. 

Specifies the hostname of the database server. 

Specifies the port which the database server listens to; for 

example 1433. 

Specifies the name (MSSQL) or SID (Oracle) that defines 

your Spotfire database. 

Specifies further options, separated with semicolons. Only 

necessary if you need to set something specific for your 

database server. This may include information such as a 

named Instance in an MSSQL server, for example. See 

example below. 

For the different supported database drivers this becomes: 

Oracle (DataDirect Driver) 

[API]:[DBDriver]:[ServerType]://[Hostname]:[Port];SID=[SID] 



Example: 

jdbc:tibcospotfireinc:oracle://dbsrv.company.com:1433;SID=spotfire_server 

Oracle (Native Driver, ojdbc6.jar) 

[API]:[DBDriver]:[DriverType]://[Hostname]:[Port];SID=[SID] 

Example: 

jdbc:j@dbsrv.company.com:1521:spotfire_server 

Microsoft SQL Server (DataDirect Driver) 

[API]:[DBDriver]:[ServerType]://[Hostname]:[Port];DatabaseName=[DBName] 

Example: 

jdbc:tibcosoftwareinc:sqlserver://dbsrv.company.com:1433;DatabaseName=spotfire_server 

Example using Integrated Authentication 


dbsrv.company.com:1433;DatabaseName=spotfire_server;AuthenticationMethod=ntlm;LoadLibra 

ryPath=c:/tibco/tss/3.2.2/tomcat/lib 

Note: Make sure that the LoadLibraryPath has the correct path to the tomcat/lib 

directory in the Spotfire Server installation directory. 

Microsoft SQL Server (Native Driver, sqljdbc4.jar) 

[API]:[DBDriver]://[Hostname]:[Port];DatabaseName=[DBName] 

Example: 

jdbc:sqlserver:// 

dbsrv.company.com:1433;DatabaseName=spotfire_server;selectMethod=cursor 

Note: Due to a restriction in the native Microsoft SQL Server driver, you may need to 

add the option responseBuffering=adaptive to your connection string. This is 

necessary if you are going to store large analysis files in the library. 

Example using Integrated Authentication: 


dbsrv.company.com:1433;DatabaseName=spotfire_server;selectMethod=cursor;integratedSecur 

ity=true; 

Note: For integrated authentication to work, you must place the file sqljdbc_auth.dll in 

a folder in the system path, such as C:\Windows\System32. This file is included with 

the native drivers from Microsoft. 


dbsrv.company.com:1433;databaseName=spotfire_server;selectMethod=cursor;responseBufferi 

ng=adaptive 



jTDS (Native Driver, jtds.jar) 

jdbc:jtds:sqlserver://[Hostname]:[Port]/[DatabaseName] 

Example: 

jdbc:jtds:sqlserver://dbsrv.company.com:1433/spotfire_server 

Microsoft SQL Server with Named Instance 

If your database server uses a named Instance, you must add an option to the end of 

the connection string to identify it. Note that this option is not limited to the jTDS 

driver. You can add this option regardless of what driver you are using. 

jdbc:jtds:sqlserver://[Hostname]:[Port]/[DatabaseName];instance=[InstanceName] 

Example: 

jdbc:jtds:sqlserver://dbsrv.company.com:1433/spotfire_server;instance=FirstInstance 

Note: To use other drivers than the DataDirect ones, you need to install them onto each 

Spotfire Server. Refer to the section “Database Drivers” on page 47 for more 



Uninstall 

12 Uninstall 

12.1 Server Software Uninstall 

For uninstall purposes, an uninstall application is created automatically upon 

installation. This application is found in the directory 

/installer/uninstaller> and is called Uninstall TIBCO 

Spotfire Server 3.2.2.exe or Uninstall TIBCO Spotfire Server 3.2.2.bin. Run this 

application and follow the directions. 

On Solaris, Red Hat, and SUSE systems, you must also remove the startup script 

/etc/init.d/tss manually (if you have installed it). 

Note: In Windows, it is also possible to start the uninstall application using “Programs 

and Features” found in the Control Panel. 

If you have placed any additional files in the installation directory or any of its 

subfolders, such as Spotfire Library export files, you should move these files to a 

secure location before uninstalling. 

If you have performed a restore from a backup of the Spotfire Server using the 

instructions in the section “Technical Reference” on page 131, there is no Uninstall 

application in place. To uninstall Spotfire Server manually, first remove the Windows 

Service, if present, by running the bat file 

/tomcat/bin/service.bat remove 

Then remove the installation directory. On Solaris, Red Hat, and SUSE systems, you 

must also remove the startup script /etc/init.d/tss manually (if you have installed 

it). 

12.2 Database Removal 

In the scripts/oracle_install/utilities and scripts/mssql_install/utilities folders on the 

Spotfire Server installation media, there are a number of scripts that can be used to 

remove the Spotfire and Demo databases: 


• drop_databases.bat. Use this if you are using database authentication with your 

Microsoft SQL server. 

• drop_databases_ia.bat. Use this if you are using Windows Integrated 

Authentication with your Microsoft SQL Server. 

Oracle 

• drop.databases.bat. Use this if your are running Oracle on a Windows server. 

• drop_databases.sh. Use this if you are running Oracle on a Unix server. 


Uninstall 

Before you run it, you must open it in a text editor and edit a number of variables. 

These variables are the same that were set during database preparation. See the section 

“Prepare the Database” on page 16 for detailed information about these variables.

TIBCO Spotfire Server 3.2.2 - TIBCO Product Documentation

You also want an ePaper? Increase the reach of your titles

Delete template?

Save as template?