TIBCO Spotfire Server 5.

5
Installation and Configuration Manual

Revision date: 20 May 2013

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 - 2013 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

Contents
1
1.1 1.2 1.3 1.4 1.5 1.6 1.7

Overview
Concepts Services System TIBCO Spotfire Server Set-Up Tuning TIBCO Spotfire Server Upgrade System Requirements

7
7 10 11 13 14 14 14

2
2.1 2.2

Preparation
Collect the Required Information Prepare the Database

15
15 17

3
3.1 3.2 3.3 3.4

Installation
The First Installation Process Install Spotfire Server Install Database Drivers Hotfix installation

23
23 23 27 27

4
4.1 4.2 4.3 4.4 4.5 4.6 4.7 4.8 4.9 4.10 4.11 4.12 4.13 4.14 4.15 4.16 4.17 4.18

Configuration
High Level Configuration Steps Configuration Tool Configuration Command Line Tool Script Language Authentication and User Directory Username and Password Authentication Methods Single Sign-On Authentication Methods Delegate Authentication Method Impersonation Configuring Login Behavior External Directories and Domains User Directory Modes Configuring HTTPS Configuring LDAPS Using Kerberos to log in to the Spotfire Database Exporting and Importing Configuration Files Configuring a Specific Directory for Library Import and Export Attachment Manager

29
30 34 40 50 53 55 58 71 72 73 74 77 88 92 93 99 99 100

5
5.1 5.2 5.3 5.4 5.5 5.6 5.7

Administration
The First Administration Process Start and Stop the Spotfire Server Manage Users and Groups Install TIBCO Spotfire for Spotfire Administrator Usage Install TIBCO Spotfire Clients on End Users Machines Enable Data Functions Usage Enable Demo Database Usage

101
101 102 104 105 106 106 107

6
6.1 6.2 6.3

Monitoring
Instrumentation Configuration Example

109
109 111 112

7
7.1 7.2 7.3 7.4 7.5 7.6 7.7 7.8

Log User Action

Introduction What is Being Logged Web Service Log File Database Logging Installation of the Log User Action Feature Some Comments TIBCO Spotfire Server and the Different Databases/Schemas

113
113 114 118 118 119 121 123 124

8
8.1 8.2 8.3 8.4

Upgrades
Upgrade to 5.5 from a Previous Version of TIBCO Spotfire Server Migration from Spotfire Analytics Server 10.1 Upgrade Between Service Pack Versions Applying Hotfixes

125
125 129 130 130

9
9.1 9.2 9.3

Backup and Restore

Spotfire Database Spotfire Server Disaster Recovery

131
131 131 133

10 Uninstallation
10.1 Uninstalling the Spotfire Server 10.2 Removing the Database

135
135 136

11 Advanced Procedures
11.1 11.2 11.3 11.4 11.5 11.6 11.7 SF.1 SF.2 SF.3 SF.4 Running Database Preparation Scripts Manually Resizing Temporary Tablespace Modifying the Virtual Memory Data Source Templates Default Join Database Creating a Self-Signed Server Certificate Creating and Installing a Self-Signed Client Certificate Server Logs and Diagnostics server.xml bootstrap.xml krb5.conf

137
137 138 138 139 150 150 152

Reference:Spotfire Server Files

155
155 157 158 159

Reference:Configuration References
CR.1 Server Bootstrapping and Database Connection Pool Configuration CR.2 Database Connection URL Examples LB.1 Prerequisites LB.2 Spotfire Server Configuration LB.3 Load Balancer Configuration LB.4 Load Balancer AJP Keyword Restriction LB.5 NTLM Authentication LB.6 Kerberos Authentication LB.7 X.509 Client Certificate Authentication LB.8 Setting up HTTPS LB.9 Configuring X.509 Client Certificates LB.10 Shared Disk Location

161
161 163 167 168 168 170 170 171 171 172 174 174

Reference:Load Balancing Reference Implementation167

Reference:Commands
> add-ds-template

177
177

> > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > >

add-member bootstrap clear-join-db config-action-log-database-logger config-action-log-web-service config-action-logger config-attachment-manager config-auth config-basic-database-auth config-basic-ldap-auth config-basic-windows-auth config-client-cert-auth config-delegate-auth config-impersonation-auth config-import-export-directory config-jmx config-kerberos-auth config-ldap-group-sync config-ldap-userdir config-login-dialog config-ntlm-auth config-post-auth-filter config-userdir config-windows-userdir create-default-config create-jmx-user create-join-db create-ldap-config create-user delete-jmx-user delete-user demote-admin enable-user export-config export-ds-template export-groups export-library-content export-users help import-config import-groups import-jaas-config import-library-content import-users list-admins list-auth-config list-auth-mode list-configs list-deployment-areas list-ds-template list-groups list-jaas-config list-jmx-users list-ldap-config list-ldap-userdir-config list-ntlm-auth list-online-servers list-post-auth-filter list-userdir-config

178 179 181 182 183 184 185 186 187 188 189 189 190 192 193 194 195 196 199 200 201 204 205 207 208 208 209 210 217 218 219 219 220 221 222 223 224 225 227 227 228 229 230 231 232 233 233 234 234 235 235 236 237 237 238 238 239 240 240

> > > > > > > > > > > > > > > > > > > > > > > > > > >

list-userdir-mode list-users list-windows-userdir-config manage-deployment-areas modify-db-config modify-ds-template promote-admin remove-ds-template remove-jaas-config remove-ldap-config run set-auth-mode set-config set-db-config set-restart-policy set-userdir-mode show-basic-ldap-auth show-config-history show-deployment show-import-export-directory show-join-database show-restart-policy switch-domain-name-style test-jaas-config update-deployment update-ldap-config version

241 241 242 243 244 246 247 247 248 248 249 249 251 251 253 254 254 255 255 256 257 257 258 259 260 261 267

Reference:Troubleshooting
> Spotfire Server Logs > Basic Troubleshooting steps > Common Issues

268
268 273 274

1 Overview

Overview
The TIBCO Spotfire Server is used by TIBCO Spotfire, TIBCO Spotfire Web Player, and TIBCO Spotfire Automation Services to identify users, assign privileges and serve as a central storage for configuration, preferences, software updates, and analyses.

TIBCO Spotfire, TIBCO Spotfire Web Player and TIBCO Spotfire Automation Services are all clients to the TIBCO Spotfire Server. When starting TIBCO Spotfire for the first time, an administrator needs to log in to a Spotfire Server and set up licenses for users. The users must activate their licenses to be able to access analyses in the Library of the TIBCO Spotfire Server.

1.1

Concepts
Groups Spotfire administrators manage groups in the Spotfire Administration Console in TIBCO Spotfire Server or in the Spotfire Administration Manager in TIBCO Spotfire.

TIBCO Spotfire Server 5.5

7 (276)

1 Overview

Groups can be structured into hierarchies where members of a child group are automatically members of all parent groups further up in the hierarchy. Properties, licenses and preferences set for parent groups are inherited to child groups.

Spotfire Groups can be synchronized from an external source and can be created and managed locally in the Spotfire database. Synchronized groups cannot be managed from within the Spotfire system, but they can be placed in manually created groups and thereby managed. Roles In the Spotfire System, there are a number of special groups that are not possible to remove, these groups shall be seen as roles. Roles represent sets of tasks that the group members are allowed to perform. To assign a role to a user, add the user (or group the user belongs to) to one of the special groups listed below. Administrator Library Administrator Deployment Administrator Diagnostics Administrator Web Player Administrator Scheduled Updates Users Script Author Everyone Impersonator Licenses TIBCO Spotfire licenses control which features are available to users. A group structure is created and licenses are set for the created groups (licenses are always set on group level). Groups can belong to groups, and licenses are inherited from parent groups. When an end user logs in to TIBCO Spotfire, only the features enabled on the groups the user belongs to appear in TIBCO Spotfire.

8 (276)

TIBCO Spotfire Server 5.5

1 Overview

Library The TIBCO Spotfire library provides convenient publishing of Spotfire files and analysis data. In the Spotfire library, users can publish and share their analysis material. A Spotfire administrator or a library manager sets up the library using the Administration Manager in TIBCO Spotfire. A folder structure is built and appropriate read and write permissions for different groups are assigned to the created folders. Packages and Deployment The features and functionality of TIBCO Spotfire are contained in software packages. The packages are bundled into a distribution folder that can be found in a folder in the installation kit. The folder is deployed on the TIBCO Spotfire Server by an administrator and TIBCO Spotfire end users install their assigned packages on their computers using the TIBCO Spotfire installer. Packages are deployed to the TIBCO Spotfire Server using the Administration Console, the Configuration Tool or the Configuration Command Line Tool.

TIBCO Spotfire Server 5.5

9 (276)

1 Overview

1.2

Services
The TIBCO Spotfire Server handles requests and provides user data to Spotfire clients from the Spotfire database. The information the TIBCO Spotfire Server needs to have continuously is stored in the Spotfire database. User Directory Services The Spotfire Server User Directory Services enables the server administrator to manage users, groups, licenses and preferences stored in the Spotfire database. The User Directory Services also performs user authentication and authorization. The TIBCO Spotfire Server can be integrated with an existing IT infrastructure. Authentication: Checking credentials against: Spotfire database

LDAP Directory Windows NT Domain Custom JAAS Module

Single sign-on: NTLM

Kerberos X.509 Client Certificate

User Directory options: Spotfire database LDAP Directory Windows NT Domain Deployment Services The Spotfire Server Deployment Services is the distribution mechanism for TIBCO Spotfire client packages and hotfixes. It enables creation and uploading of Packages to the Spotfire Server. The Deployment Services enables upgrading of TIBCO Spotfire clients from a central repository. When TIBCO Spotfire is started, it checks for available updates and if found, users are required to confirm download and install the latest version. The packages are stored in the Spotfire database. Information Services The Spotfire Server Information Services accesses and transforms analysis data from data sources. Users can create Information Links to connect to external JDBC databases and thereby access and load data into Spotfire analysis files. Information Links and the elements they are created from are stored in the Spotfire database.

10 (276)

TIBCO Spotfire Server 5.5

1 Overview

The supported data sources may be databases of various types, for example Oracle, SQL Server, DB2, MySQL, SAS, and Teradata. Not explicitly supported databases may work if JDBC drivers exist and additional configuration is performed. Library Services The Spotfire Server Library Services enables end users to share analyses in a central repository for analysis files. The library also stores other items needed to perform analyses. When selecting save to Library, the analysis file is stored in the Spotfire database and can be shared with other users. Access to files stored in the Library is set up by user access permissions. TIBCO Spotfire users can save Spotfire analyses either to a local file system or to the Library, but analysis files must be saved to the Library for users to be able to open them in the Spotfire Web Player.

1.3

System
An advanced TIBCO Spotfire system setup may include clustering as well as encryption of the communication using HTTPS, LDAPS and Secure JDBC:

See Authentication and User Directory on page 53, Configuring HTTPS on page 88, and Configuring LDAPS on page 92 for details on security options. TIBCO Spotfire Server Clustering The main purposes for clustering TIBCO Spotfire Servers are fail-over support and load balancing. The load balancer must support session affinity, which means that within the cluster of servers, requests from the same client are always routed to the same server. Each server stores its connection information locally and then reports its availability in the cluster by writing to the database. The first server that writes to the database marks
TIBCO Spotfire Server 5.5

11 (276)

1 Overview

itself as the primus server, this makes it responsible for tasks that only should be handled by one server per cluster, for instance synchronization of external LDAP users and groups. If this server goes down, another server will automatically take over the status as primus. The database is the mechanism that enables clustering, in a clustered setup all servers use the same database. For security and performance reasons it is recommended not to install a TIBCO Spotfire Server on the same machine as the database, not even in a non-clustered system. TIBCO Spotfire Server connects to its database Oracle or Microsoft SQL Server using a JDBC driver. Configuration TIBCO Spotfire Server configuration is performed by a graphical Configuration Tool or a Configuration Command Line Tool. The Configuration Tool guides the user through the configuration process and provides test features and feedback during configuration. The Configuration Command Line Tool enables scripting and provides advanced configuration capabilities. In the tools, each configuration is stored as a specific object with a specific name, and is added to a list of configurations that includes timestamps and comments. This enables administrators to switch between configurations and also to test different configurations. For information about the Configuration Tool, refer to section: Configuration Tool on page 34 An introduction to commands and their usage is given in the following sections: Configuration Command Line Tool on page 40

Creating a Simple Configuration using the Configuration Command Line Tool on page 42 Scripting a Configuration on page 51 Authentication and User Directory on page 53 Available Configuration Commands on page 44 and the reference Commands on page 177

12 (276)

TIBCO Spotfire Server 5.5

1 Overview

1.4

TIBCO Spotfire Server Set-Up

TIBCO Spotfire Server is set up in four general steps: preparation, installation, configuration and administration. Actions indicated as recommended or optional may be performed later. Scripts, installers, tools, and applications are provided on the installation kit. Preparation

Collect the required information (15) Prepare the Spotfire database (17)

Installation

Run the Spotfire Server installer, interactively (using interface) or silently (using batch file) (23) Recommended: Install database drivers (27) Install the latest hotfix, if any (27)

Configuration

Create a Spotfire Server configuration (Simple 42) Recommended: Further configure the Spotfire System (53) Optional: Set up load balancing (See page Load Balancing Reference Implementation)

Administration

Start the TIBCO Spotfire Server (102) Define Users and Groups (104) Deploy client packages to the Spotfire Server (105) Install TIBCO Spotfire for the Spotfire Administrators usage (105) Assign Licenses and define Preferences (105) Install Spotfire clients on end users machines (106) Recommended: Enable use of the Data Functions (106) In order to use these Data Functions, TIBCO Spotfire Statistics Services needs to be installed and configured as well. Spotfire 5.5 features pre-packaged predictive analytic methods in the form of Data Functions. These Data Functions provide Spotfire users immediately useful analytic functionality, as well as detailed and flexible templates to help users develop their own Data Functions more quickly and easily. Installing these Data Functions will make these features potentially available to your users. Optional: Enable use of the Demo Database (107)

TIBCO Spotfire Server 5.5

13 (276)

1 Overview

1.5

Tuning
Temp Folder The TIBCO Spotfire Server has a temp folder that is used to keep temporary files during uploads and downloads from the TIBCO Spotfire Server. It is recommended that this temp folder <installationdir>\tomcat\temp\ is excluded from anti-virus checks. Ports The Spotfire Server listens to the following ports, some may have to be modified:
Listener Spotfire Server (HTTP) Spotfire Server (HTTPS) Spotfire Server (JMX) Spotfire Server (AJP) Tomcat Shutdown Default Port 80 Disabled (443) Disabled (1099) Disabled (8009) 9005

Note: The Tomcat shutdown port is used to control the life cycle of the Spotfire Server application. This port is used locally and must not be exposed through the firewall.

1.6

TIBCO Spotfire Server Upgrade

If you are running TIBCO Spotfire Server 3.0 or later, you can perform an upgrade to Spotfire Server 5.5 using the Upgrade Tool distributed with the TIBCO Spotfire Server. The tool enables the 5.5 server to upgrade the database, and it copies the configurations from the previous server installation. See Upgrades on page 125.

1.7

System Requirements
Prior to installing Spotfire Server, verify that your system complies with the latest system requirements at http://support.spotfire.com/sr.asp. Refer to the TIBCO Spotfire Server 5.5 Release Notes for changes in this version.

14 (276)

TIBCO Spotfire Server 5.5

2 Preparation

Preparation
Upgrading? If you are upgrading, first read Upgrades on page 125.

2.1

Collect the Required Information

Identify and record the system properties prior to installing Spotfire Server 5.5. Below is a checklist to help Administrators to identify the required information. Note : When installing Spotfire Server, you will run scripts distributed with the installer. The scripts will create and prepare a database. See Prepare the Database on page 17. Database server Database server type: There must be a database server up and running before installing TIBCO Spotfire Server. The Spotfire Server installer will not install a database server. It is recommended that the database server is run on a dedicated, separate machine. Spotfire supports Oracle or Microsoft SQL Server. Database server hostname: Database server administrator username: Database server administrator password: SID (Oracle)/Instance name (MSSQL): Spotfire Database
When you set up the Spotfire database, you will create databases and database users.

Spotfire database name (MSSQL only):

The Spotfire database name only applies to MSSQL, and the default is spotfire_server.

TIBCO Spotfire Server 5.5

15 (276)

2 Preparation

Spotfire database username:

If the database uses Windows Integrated Authentication, note this user here. If you use Integrated Authentication, the Spotfire Server must run as this Windows Domain user.

Spotfire database password: TIBCO Spotfire Server TIBCO Spotfire Server Listen port:
The Spotfire Server installer will ask for a server listen port. The default is 80. If you are installing Spotfire Server on a machine that is already running other applications, make sure not to select a port that is already in use by these applications. The default port number is the same as in previous versions of TIBCO Spotfire Server. If you want to continue to run a previous version of Spotfire Server on the same machine, select a different port number. Selecting a port number already in use may result in failure to start the servers. Refer to Ports on page 14 and Basic Troubleshooting steps on page 273 for details.

TIBCO Spotfire Server Login method:

Knowledge about your organizations IT infrastructure is required to set up any login method other than Spotfire Database.

Username and password login Single sign-on login

Valid options: Spotfire Database, LDAP, Custom JAAS, Windows NT Domain Valid options: NTLM, Kerberos, X.509 Client Certificate Refer to Authentication and User Directory on page 53 for details.

TIBCO Spotfire Server User Directory mode:

Knowledge about your organizations IT infrastructure is required to set up any user directory mode other than Spotfire Database. Valid options are: Spotfire Database, LDAP, and Windows NT Domain. Refer to Authentication and User Directory on page 53 for details.

TIBCO Spotfire Server operating system: TIBCO Spotfire Server(s) Hostname(s):

Optional: Hostname of load

balancer:

16 (276)

TIBCO Spotfire Server 5.5

2 Preparation

2.2

Prepare the Database

Before you run the TIBCO Spotfire Server installer, you must set up the Spotfire database. This is performed by modifying scripts and running them. You can use either an Oracle database server or a Microsoft SQL Server to hold your Spotfire Server database. Depending on your choice, continue to either:

Oracle on page 17 Microsoft SQL Server on page 19

2.2.1 Oracle
2.2.1.1 Prerequisites
The following settings must be configured on the Oracle Server in order for the scripts to work, and for the TIBCO Spotfire Server to be able to communicate with the databases:

The Oracle Server must be configured to use username and password authentication to run the scripts. However, it is possible to set up the Spotfire Server to authenticate with an Oracle database instance using Kerberos. See the section Using Kerberos to log in to the Spotfire Database on page 93. 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. Talk to your database administrator or refer to the Oracle database documentation for more information.

2.2.1.2 Copy the Scripts to the Database Server

The scripts run commands that needs to communicate with the Spotfire database. Therefore it is recommended to copy the content below to the database server. Use any machine that can run Oracle tools and can communicate with the Spotfire Server. 1 2 On the installation kit, locate the directory scripts/oracle_install Copy the entire directory to a temporary place on the local disk of your intended database server. Comment: The command line database tools (sqlplus etc.) must be in the system path of the database server.

TIBCO Spotfire Server 5.5

17 (276)

2 Preparation

2.2.1.3 Modify the create_databases Script

In the copied folder, locatecreate_databases.bat (Windows) or create_databases.sh (Solaris/Red Hat Enterprise Linux/SUSE Linux Enterprise). Open the file in a text editor and locate the following section:
rem set set set set set set set set rem set set set Set these variable to reflect the local environment: ROOTFOLDER=<ROOTFOLDER> CONNECTIDENTIFIER=<SID> ADMINNAME=system ADMINPASSWORD=<ADMINPASSWORD> SERVERDB_USER=<SERVERDB_USER> SERVERDB_PASSWORD=<SERVERDB_PASSWORD> SERVER_DATA_TABLESPACE=SPOTFIRE_DATA SERVER_TEMP_TABLESPACE=SPOTFIRE_TEMP Demo data parameters INSTALL_DEMODATA=no DEMODB_USER=spotfire_demodata DEMODB_PASSWORD=spotfire_demodata

Specify the following variables.

ROOTFOLDER. The location where the tablespaces will be created. It must be a directory that is writable for the Oracle server, usually <oracleinstalldir>/ oradata/<SID>. Note: Do not add a slash or backslash after the <SID>. CONNECTIDENTIFIER: The Oracle TNS name/SID of the database. ADMINNAME: The name of a user with database administrator privileges, default is systemaccount. ADMINPASSWORD: The password of the above user. SERVERDB_USER: The user that will be created and later used to access the Spotfire database. SERVERDB_PASSWORD: The password of the above user. SERVER_DATA_TABLESPACE: The name of the tablespaces that will be created. The default value will work for most systems. SERVER_TEMP_TABLESPACE: The name of the temporary tablespaces that will be created. The default value will work for most systems. Note : Confilicting tablespaces can occur if you are creating the Spotfire tablespaces on a database server that is already hosting an Analytics Server or a previous version of Spotfire Server. Make sure that you do not select any names for the 5.5 tablespaces and users that conflicts with the already hosted tablespaces and users. INSTALL_DEMODATA: If you need demodata, alter this variable from default no. The demo database contains example data for learning about Spotfire. Do not change the default username. If you install the demo database, you must perform additional steps to make the data available to the users: See Enable Demo Database Usage on page 107.

Save the file and exit the text editor.

18 (276)

TIBCO Spotfire Server 5.5

2 Preparation

2.2.1.4 Run the create_databases.bat/.sh Script

Once the scripts have been set up, run the create_databases.bat or create_databases.sh script. Running these scripts will execute the other SQL scripts in the folder. 1 2 3 Open a command prompt window.
Navigate to the directory where you placed the scripts. Type create_databases.bat or create_databases.sh and press Enter.

Response: The scripts now set up the Spotfire database required by Spotfire Server, and optionally the Spotfire Demo Database. This may take a while. Response: The log.txt file is created in the same directory as the create_databases file. Also, if you selected to have demodata, 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. Note: Please retain the logs for future reference. Note: There is sensitive information in the scripts. It is recommended to remove the scripts after they have run. Proceed to Install Spotfire Server on page 23 when finished.

2.2.2 Microsoft SQL Server

There are different scripts provided for Microsoft SQL Server. Which to select depends on if you intend to set up Windows Integrated authentication or username and password authentication between the Spotfire Server and the Spotfire database:

For username and password authentication on Microsoft SQL Server, use create_databases.bat. For Windows Integrated authentication (IA) on Microsoft SQL Server, use create_databases_ia.bat.

2.2.2.1 Prerequisites
The following settings must be configured on the Microsoft SQL Server in order for the scripts to work, and for the TIBCO Spotfire Server to be able to communicate with the databases:

TCP/IP communication must be enabled. A TCP/IP listener port must be configured. (The 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).

TIBCO Spotfire Server 5.5

19 (276)

2 Preparation

2.2.2.2 Copy the Scripts to the Database Server

The scripts run commands that needs to communicate with the Spotfire database. Therefore it is recommended to copy the content below to the database server. Use any machine that can run Microsoft SQL tools and can communicate with the Spotfire Server. 1 2 In the installation kit, locate the scripts directory: scripts/mssql_install Copy the entire directory to a temporary place on the local disk of your intended database server. Comment: The command-line database tools (sqlcmd, and so forth) must be in the system path of the database server.

2.2.2.3 Modify the create_databases.bat Script

In the copied folder locate create_databases.bat or create_databases_ia.bat. 1 Open the file in a text editor and locate the following section:
rem set set set set set set rem set set set set Set these variable to reflect the local environment: CONNECTIDENTIFIER=<SERVER>\<MSSQL_INSTANCENAME> ADMINNAME=sa ADMINPASSWORD=<ADMINPASSWORD> SERVERDB_NAME=spotfire_server SERVERDB_USER=<SERVERDB_USER> SERVERDB_PASSWORD=<SERVERDB_PASSWORD> Demo data parameters INSTALL_DEMODATA=no DEMODB_NAME=spotfire_demodata DEMODB_USER=spotfire_demodata DEMODB_PASSWORD=spotfire_demodata

Specify the following variables.

CONNECTIDENTIFIER: Replace <SERVER> with the name of the server running the SQL Server instance, and replace <MSSQL_INSTANCENAME> with the name of the SQL Server instance. ADMINNAME: The name of a user with admin privileges on the database, usually sa. This is not used if you are using Windows Integrated Authentication. ADMINPASSWORD: The password of the above user. It is not used if you are using Windows Integrated Authentication. SERVERDB_NAME: The name of the database that will be created. SERVERDB_USER: The user that you wish to create and use for this database. SERVERDB_PASSWORD: The password for the above user. It is not used if you are using Windows Integrated Authentication.

20 (276)

TIBCO Spotfire Server 5.5

2 Preparation

INSTALL_DEMODATA: If you need demodata, alter this variable from default no. If you want to create the demo database, do not change the default database name and username. Make sure that the database server does not have a database or a user with these names already. If you install the demo database, you must perform additional steps to make the data available to the users. See Enable Demo Database Usage on page 107. WINDOWS_LOGIN_ACCOUNT: The Windows Login Account that is used to authenticate with the database server. This is only used when using Windows Integrated Authentication.

Note: When using Windows Integrated Login, the create_server_user_ia.sql script creates a database user associated with the WINDOWS_LOGIN_ACCOUNT name. By default, it is assumed that a Windows login with this name already exists. If it does not exist, 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)] */

Save the file and exit the text editor. Case Sensitive Collation If your database server by default is set to use a case sensitive collation, you must specify that the Spotfire database shall be case insensitive. Edit the SQL script create_server_db.sql:

1 2 3

Open this file in a text editor. Locate the commented out line:
--create database $(SERVERDB_NAME) collate Latin1_General_CI_AS;

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. Comment out the line below it by inserting leading :
create database $(SERVERDB_NAME)

4 5

Save the file and exit the editor.

TIBCO Spotfire Server 5.5

21 (276)

2 Preparation

2.2.2.4 Run the create_databases Script

Once the scripts have been 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 2 3 Open a command prompt window.
Navigate to the directory where you placed the scripts. 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. Response: 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. Note: Please retain the logs for future reference. Note: There is sensitive information in the scripts. It is recommended to remove the scripts after they have run. Proceed to Install Spotfire Server on page 23 when finished.

22 (276)

TIBCO Spotfire Server 5.5

3 Installation

Installation
This chapter describes the installation of Spotfire Server including post-installation steps. Running the installer, both in interactive and silent mode, is described. Upgrading? If you are upgrading, first read Upgrades on page 125.

3.1
1 2 3

The First Installation Process

Run the Spotfire Server installer, interactively or silently (3.2) Recommended: Install Database Drivers (3.3) Install the latest hotfix, if any (3.4)

3.2

Install Spotfire Server

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. It is recommended to install the 64-bit version of Spotfire Server unless there are specific reasons not to. In the installation kit, locate the installer for your system: Windows: setupwin32.exe or setupwin64.exe RPM Linux: tss5.5.0.x86_32.rpm or tss5.5.0.x86_64.rpm Solaris: install.bin Three major components will be installed: A Java Environment (JDK), a Tomcat Application Server and a TIBCO spotfire Server web application. The JAVA_HOME of the Apache Tomcat is set to the path of the installed JDK. Note: Consider installing the Java Cryptography Extension (JCE) unlimited strength jurisdiction policy files. It is the user's responsibility to verify that these files are allowed under local regulations. Windows Specifics The native Windows installer can be run interactively or silently. RPM Linux Specifics The RPM based Linux installer can be launched from the command line or interactively. The post-install script must then be launched from a command line. This script accepts arguments on the command line, or will interactively ask for them if they are missing. Solaris Specifics The TIBCO Spotfire Server is installed on Solaris using the InstallAnywhere technology, which is also used by previous Spotfire Server versions.

TIBCO Spotfire Server 5.5

23 (276)

3 Installation

JCIFS for NTLM Authentication Third party components are needed to configure the system for NTLM, these can be automatically downloaded as a step in the installation, or manually downloaded at a later point. To manually download the files, go to http://public.tibco.com/pub/tibco_oss/jcifs/ jcifs_1.3.17.zipand copy jcifs_1.3.17.zip(which contains the file jcifs.jar) to the<installa tiondirectory>/tomcat/webapps/spotfire/WEBINF/lib/ folder.

3.2.1 Interactive Installation

Windows Note: If you already have a TIBCO Spotfire Server 5.5.0 installed, clicking Next in the welcome dialog will display the Program Maintenance dialog containing Remove and Repair options. Select Repair to write installed files to the hard drive again or Remove to uninstall TIBCO Spotfire Server 5.5.0. 1 Run the selected installer. Note: If you use Microsoft SQL Server with Windows Integrated Authentication, install the Spotfire Server as the Domain User that you set up with the script create_databases_ia.bat. Also make sure that the Spotfire Server always runs as this Domain User, see Windows, Service Exists, Integrated Authentication for SQL Server on page 103. Confirm with the logs that the Spotfire Server starts. The Welcome dialog is displayed. Click Next. The TIBCO License dialog is displayed. Read the license agreement and select the appropriate radio button. Click Next. The Third Party Components dialog is displayed. These components are only needed to configure the system for NTLM. See JCIFS for NTLM Authentication on page 24. Click Next. If you select to download third party components, the Third Party License dialog is displayed. Read the license agreement and select the appropriate radio button. Click Next. The Destination Folder dialog is displayed. Specify the Spotfire Server location. Click Next. The Windows Service dialog is displayed. Select the option you want. Click Next. The Spotfire Server Port dialog is displayed. Specify the Spotfire Server port, for details See Ports on page 14. Click Next.

2 3

5 6 7

24 (276)

TIBCO Spotfire Server 5.5

3 Installation

The Ready to Install the Program dialog is displayed. Click Install. Response: The installation starts. The Completed dialog provides three options: Launch the configuration tool: Select this option to start configuring the TIBCO Spotfire Server using the Configuration Tool, See Configuration on page 29.

Launch the upgrade tool: Select this option if you are performing an upgrade from a previous version of TIBCO Spotfire Server and want the upgrade tool to start automatically when the installer finishes. Exit the Installation Wizard.

Select the Show the Windows Installer log option to see the log when the installer finishes. Click Finish. RPM Linux For RPM Linux the interactive installer provides panels for the choice to install, to provide the password, and for progress. Post-install configuration must be performed in a command prompt. You must run the installer as root. 1 2 3 Launch /user/local/bin/tibco/tss/5.5.0/configure Select whether to download and install third party components. Default is yes. Specify the Spotfire Server port. Default is 80, See Ports on page 14. Solaris 1 2 3 4 Run the installer. The Introduction dialog is displayed. Click Next. The TIBCO License dialog is displayed. Select a radio button. Click Next. The Third Party Components dialog is displayed. These components are only needed to configure the system for NTLM. See JCIFS for NTLM Authentication on page 24. Click Next. 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 appropriate radio button. Click Next. The Installation Folder dialog is displayed. Specify the install location. Click Next. The OS Architecture dialog is displayed. Select whether you want to install the 32-bit or 64-bit version of TIBCO Spotfire

5 6

TIBCO Spotfire Server 5.5

25 (276)

3 Installation

7 8 9

10

Server. The 64-bit version can only be installed on a 64-bit operating system. The 32-bit Solaris version can be installed on either a 64-bit or a 32-bit operating system. Click Next. The Spotfire Server Port dialog is displayed. Specify the port, See Ports on page 14. Click Next. The Installation Summary dialog is displayed. Click Install. The Upgrade dialog is displayed. If you are performing an upgrade from a previous version of TIBCO Spotfire Server, select to start the upgrade tool automatically when the installer finishes. Click Next. The Install Complete dialog is displayed. Click Done.

3.2.2 Command Line Installation

Windows To launch a silent installation, run the (Windows x64) installer as follows:
setupwin64.exe /s /v"/qn /l*vx c:\setup.log DOWNLOAD_THIRD_PARTY=Yes INSTALLDIR=c:\tibco\tss\5.5.0 SPOTFIRE_WINDOWS_SERVICE=Create SERVER_PORT=80"

Arguments: DOWNLOAD_THIRD_PARTY: Can be one of {Yes, No}. See JCIFS for NTLM Authentication on page 24. SPOTFIRE_WINDOWS_SERVICE: Can be one of {Create, DoNotCreate}. See step 6 on page 24. Specify /qn for quiet installation with no user interface. Specify /qb for quiet installation with basic user interface. RPM Linux To launch a silent installation, run rpmivhtss5.5.0.x86_<32>.rpmor
rpmivhtss5.5.0.x86_<64>.rpm

Use the post-install configuration arguments:

/user/local/bin/tibco/tss/5.5.0/configure [d] [s <server port>] where d disables the download of third party components.

Solaris To create a silent installation, first record a response file. To record, type: install.binr <path>/silent.properties and specify a path to the file, where the path should be an absolute path. To run the installer silently: install.bin i silent f <path>/silent.properties. If no path is specified to the properties file, it is assumed it is located in the same folder as the install.bin.

26 (276)

TIBCO Spotfire Server 5.5

3 Installation

3.3

Install Database Drivers

The Spotfire Server ships with DataDirect database drivers. While these drivers work well for test environments as described above, it is strongly recommended that drivers from your database server vendor are used in a production environment. Vendor drivers (JDBC) are available to download from Microsofts and Oracles homepages. Place them in the <installationdir>/tomcat/lib directory. When you have installed the database drivers, the Spotfire Server needs to be restarted according to the instructions in the section Start and Stop the Spotfire Server on page 102. Note: The database connection URL, used by the server to connect to the database, may differ for different database drivers. See Database Connection URL Examples on page 163 for the database connection URL and for database driver examples. Data Sources in the Information Designer The Information Designer tool, available in TIBCO Spotfire, allows users to create analyses based on data retrieved from external JDBC sources. These external data sources are accessed using database drivers. Any database drivers you install in the folder mentioned 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 database and a specific database driver. Use the Configuration Tool or the command add-ds-template on page 177.

3.4

Hotfix installation
Before you continue, please check if there is a relevant hotfix for this version of Spotfire Server. If there are, install the latest, every hotfix is cumulative, which means that you only need to install the latest. 1 2 Check the URL http://support.spotfire.com/patches_spotfireserver.asp and download the latest hotfix. Installation instructions for each hotfix are included in the package. Always make sure you have installed the latest hotfix before troubleshooting or reporting any problems. When you have installed a possible hotfix, the next step is to configure the Spotfire system. See Configuration on page 29.

TIBCO Spotfire Server 5.5

27 (276)

3 Installation

28 (276)

TIBCO Spotfire Server 5.5

4 Configuration

Configuration
TIBCO Spotfire Server configuration The TIBCO Spotfire Server is configured using: 1 Configuration Tool, started using uiconfig.bat/uiconfig.shor

Configuration Command Line Tool, executed using config.bat/con fig.sh. This tool enables configuration scripting and provides advanced configuration capabilities.

The Configuration Tool is presented in Section 4.2 on page 34 and an introduction to the Configuration Command Line Tool is presented in Section 4.3 on page 40. When the Spotfire database has been set up, and the server is installed, a minimum amount of configuration is required to get a system running. (See Creating a First Configuration on page 31.) Available commands are grouped by function in Section 4.3.3 on page 44 and detailed command documentation is listed alphabetically by command in the reference Commands on page 177.

TIBCO Spotfire Server 5.5

29 (276)

4 Configuration

4.1

High Level Configuration Steps

Configuring the TIBCO Spotfire Server is a three-step procedure. Also see the TIBCO Spotfire Server Quick Start Guide for basic steps. 1 Create a bootstrap file The bootstrap file contains database connection information and is required to connect to the Spotfire database. Create a configuration A completed configuration contains settings for the authentication components, the User Directory, the Spotfire Library etc. During the configuration procedure, the Configuration Tool keeps the configuration in memory and the Configuration Command Line Tool creates and modifies the configuration as a configuration.xml file. Save/Import the configuration The configuration has to be saved from the Configuration Tool, or imported from the Configuration Command Line Tool, to the Spotfire database. When the Spotfire Server starts, it reads the configuration from the database.

30 (276)

TIBCO Spotfire Server 5.5

4 Configuration

4.1.1 Creating a First Configuration

The Spotfire Server provides a broad set of configuration options, which ones to use depends on the installation environment, requirements etc. One alternative is to apply a configuration workflow where a simple database configuration or a simple LDAP configuration is set up, then tested, and then further configuration is performed.

Another alternative is to apply a configuration workflow where all configuration is performed before testing the setup.

Further configuration options are listed below:

Authentication User Directory Modes

Username and Password (4.6) Spotfire database LDAP Directory Windows NT Custom JAAS Single Sign On (4.7) NTLM Kerberos X.509 Certificates Delegated Authentication (4.8) Impersonation (4.9) Post Authentication Filter (4.5.3) Blocking Mode Auto Creating Mode Chained Custom Filter

Spotfire database (4.12.1) LDAP (4.12.2) Windows NT (4.12.3)

Login Behavior (4.10) Additional Security

HTTPS (4.13) LDAPS (4.14) LDAP SASL (4.6.3) Kerberos for Spotfire database (4.15)

Exporting and Importing Configuration Files (4.16) Configuring a Specific Directory for Library Import and Export (4.17) Load Balancing (page 167)

TIBCO Spotfire Server 5.5

31 (276)

4 Configuration

For information how to create a simple configuration in different ways, see sections: Creating a Simple Configuration using the Configuration Tool on page 39. Also see the TIBCO Spotfire Server Quick Start Guide. Creating a Simple Configuration using the Configuration Command Line Tool on page 42 Scripting a Configuration on page 51

4.1.2 Configuration Procedure After the First Configuration

It is possible to update configurations using the Configuration Tool or the Configuration Command Line Tool. It is also possible to configure the TIBCO Spotfire Server by editing a local copy of the configuration.xml file, then import it and thereby setting it as the active configuration. Editing the xml-file can also be used to configure complex features in XML rather than by commands. This procedure is described in Exporting and Importing Configuration Files on page 99.

To update a server configuration in the Configuration Tool: Note: The configuration Tool is described in Configuration Tool on page 34. Start the Configuration Tool Connect to the Spotfire Database If you have already run the tool and created a bootstrap file placed in the <installation dir>/tomcat/webapps/spotfire/WEBINF directory, the Configuration Tool will open this and prompt for its tool password. Enter the tool password.

2 3 4 5

The active configuration is loaded into the Configuration Tool. Perform your changes to the configuration in the Configuration tab. Import the configuration into the Spotfire Server by clicking Save. Start or restart the Spotfire Server. To update a server configuration in the Command Line Configuration Tool: Note: The Configuration Command Line Tool described in Configuration Command Line Tool on page 40. Launch a command prompt. In Windows, select Start > Command Prompt. Run the exportconfig command to export the configuration from the Spotfire database to a configuration file. Example, where configuration.xml is optional and the f (force) is not applied:
TIBCO Spotfire Server 5.5

1 2

32 (276)

4 Configuration

> config exportconfig configuration.xml

Update the configuration in the configuration file using selected commands. Example, where configuration=configuration.xml is optional:
> config configauth configuration=configuration.xml authmethod=BASIC jaasdatabase

Choose restart policy and run the setrestartpolicy command. Example, where configuration=configuration.xml is optional:
> config setrestartpolicy configuration=configuration.xml policy= AUTOMATIC_ON_IDLE

Run the importconfig command to import the updated configuration file into the Spotfire database. Example, where configuration.xml is optional:
> config importconfig comment="SwitchedtoBASICauthenticationusingtheSpotfire Databaseauthenticationsource" configuration.xml

6 7

Optionally restart the server(s) if the restart policy is set to MANUAL. Optionally remove the configuration.xml files or restrict the access permissions to it. Note: Do not remove the bootstrap.xml file. See bootstrap.xml on page 158.

TIBCO Spotfire Server 5.5

33 (276)

4 Configuration

4.2

Configuration Tool

The Configuration Tool can be launched: Via the start menu. By selecting Launch the Configuration Tool (last step in the installation wizard). By running the uiconfig.bat file (run uiconfig.sh on RPM Linux). These files are located in the <installationdir>\tomcat\bin folder. Always run the Configuration Tool as an administrator. When launching the Configuration Tool, the System Status tab is displayed. Note: If there already is a bootstrap.xml file in the <tomcat\webapps\spotfire\WEBINF> folder, a Specify Tool Password dialog is displayed. Enter the Configuration Tool password and click OK to unlock the bootstrap file (see Bootstrap tab on page 37. for information of the Configuration Tool Password). Click Cancel to close the dialog and display the System Status tab.
34 (276)
TIBCO Spotfire Server 5.5

4 Configuration

Navigate in the tool by clicking the links in the System Status tab and/or the tabs at the top. The Configuration Tool contains five tabs where selections can be made: System Status tab Bootstrap tab Configuration tab Administration tab XML View tab System Status tab This tab shows the status of the configuration and presents five tasks. Complete the tasks from top to bottom. The tasks are preceded by a green check mark or a red cross. Green check mark: a valid alternative is selected for the task. Red cross: a valid alternative is not selected for the task. The tasks can be modified regardless of symbol. A greyed out task means that a preceding task is not completed. The tasks are followed by links that shortcuts to the place where the setting is altered in the Configuration Tool. The Client Packages Deployed on Default Area task can also be performed in the TIBCO Spotfire Administration Console. The five tasks in the System Status tab are presented below: 1 Connect to Database This task deals with bootstrap files. The bootstrap.xml file contains database connection information. Click the appropriate link to create a new bootstrap file or use an existing file. Specify Configuration The configuration contains all Spotfire Server settings. Multiple configurations can be stored in the Spotfire database, but only one can be active. Note: If there is an active configuration in the Spotfire database, the Configuration Tool will try to load it. Click the appropriate link under the Specify Configuration task to specify the configuration you wish to work on in the following tasks 3-5: To create a new configuration, click Create new configuration. To modify an existing configuration located in the Spotfire database, click Load configuration from database. To select an existing configuration and set it active, click Set configuration to be used by server. For experienced users who want to edit xml:

To modify an existing configuration from file, click Load configuration from file. To export a configuration from the Spotfire database, click Export configuration from database. Configure Spotfire Server Settings Click the link to access the Configuration tab.

TIBCO Spotfire Server 5.5

35 (276)

4 Configuration

Specify Server Administrator A user must be promoted to administrator in order to administrate the Spotfire environment. Click the Specify Server Administrator link to access the Administration tab and fulfill the task. Client Packages Deployed on Default Area Click the link to deploy client packages to the default deployment area. Note: This function should only be used to deploy the Spotfire Client packages that are required for all installations. To deploy any additional packages, use the Administration Console. Note: In the Spotfire Administration Console, Client packages can be deployed to any of the existing deployment areas in the Spotfire database (not only the default deployment area). If a deployment exist on another area than the default, this task will be marked with a red cross even though a valid deployment exists. You can create, delete and rename deployment areas and also change the default deployment area in the TIBCO Spotfire Administration Console, see "Deploy TIBCO Spotfire" on page 105 and the TIBCO Spotfire Administration Console help for more information.

36 (276)

TIBCO Spotfire Server 5.5

4 Configuration

Bootstrap tab The Bootstrap tab has two alternative presentations: Create new Bootstrap file and View Bootstrap File. To create a new bootstrap file, enter information in the fields and click Create Bootstrap.
Path Specify where the bootstrap file will be located. The bootstrap file must be located in the default path for the Spotfire Server to be able to use it. Select from drop-down menu. Select from drop-down menu. The name of the JDBC driver class. This field is pre-populated from selections made and can not be edited. The name of the database account used by the TIBCO Spotfire Server to connect to the Spotfire database. Enter correct database login details. The password of the database account. Enter correct database login details. This field is not relevant when using Windows Integrated Authentication. Enter the database hostname. Enter the Spotfire database port. Enter Server ID. Enter the database name. The JDBC connection URL. This field is pre-populated from selections made and can be edited. Enter a Configuration Tool password of your own choice. This will be used to protect the server configuration from un-authorized access. Note: The Configuration Tool password will be required when running the Configuration Tool now and later. Enter a unique name for the TIBCO Spotfire Server of your own choice. Enter an encryption password of your own choice. This will be used for encrypting other passwords stored in the database. Note that the passwords are encrypted with a static key if no encryption password is specified here. Also note that in a clustered environment, the same encryption password must be specified for all servers in the cluster.

Database server JDBC driver Driver Class

Database username

Database password

Hostname Port SID (for Oracle) Database name (for MS SQL) Database URL

Configuration Tool Password

Server Name Encryption Password (optional)

Note: Some fields are pre-populated, and most of these can also be altered manually.

TIBCO Spotfire Server 5.5

37 (276)

4 Configuration

Configuration tab Configure all Spotfire Server settings to be used in the specified configuration. In order for any configuration changes to take effect, the configuration must be saved to the Spotfire database, this is done by clicking Save configuration. If the Spotfire database already has been configured and contains an active configuration, this will be loaded into the Configuration Tool. If this is the case, navigate to the System Status tab and click the Create new configuration link. This will create a new default configuration and show it in the Configuration Tool. Available panels:
Authentication User Directory Domain Post Authentication Filter Delegate Impersonation Monitoring (JMX) Restart Policy See Authentication and User Directory on page 53. See User Directory Modes on page 77. See External Directories and Domains on page 74. See Authentication and User Directory on page 53. See Delegate Authentication Method on page 71. See Impersonation on page 72. See Monitoring on page 109. This panel is used to set the way the server reacts to configuration changes. Each server periodically checks for configuration changes and handles any such changes according to the Restart Policy. MANUAL: changes do not have any effect until the server(s) are manually restarted AUTOMATIC_FORCE: The server(s) are immediately automatically restarted. AUTOMATIC_ON_IDLE: The server(s) are automatically restarted when considered idle. Note: The AUTOMATIC_FORCE option may result in currently running user operations being aborted. Login Dialog Data Source Templates Attachment Manager User Action Log See Configuring Login Behavior on page 73. See Data Source Templates on page 139. See Attachment Manager on page 100. See Log User Action on page 113.

38 (276)

TIBCO Spotfire Server 5.5

4 Configuration

Database Properties

This panel is used to modify the common configuration for the connection to the Spotfire Server database. This configuration (which affects all servers) will be merged with the configuration in the bootstrap.xml file on each server. This panel is used to configure the default join database. If a join is made between data residing on two (or more) different datasources an attempt is made to copy the data from one of the datasources to the other to perform an SQL join. If the involved datasources do not allow writing then the join is performed using the default join data source.

Join Database

See referenced chapters for details. Navigate between the settings in the tree-structure in the upper left corner in the Configuration Tool. Administration tab The Spotfire server needs an Administrator.

If configuring an LDAP User Directory or a Windows NT User Directory, search for users, select a user and click Promote. If not using LDAP, enter username and password in the Create new user fields and click Create. Select the user and click Promote.

XML View tab This tab displays the content of the tool's currently loaded configuration in XML format. The tab is read-only.

4.2.1 Creating a Simple Configuration using the Configuration Tool

1 2 Start the Configuration Tool. On the System Status tab, click Create new Bootstrap. Response: The Bootstrap tab is displayed. 3 Enter information in the fields. See Bootstrap tab on page 37. Click Create bootstrap Response: The Configuration Tool checks that database drivers are installed and that the database is running. It also checks that the database accepts the given credentials. A dialog is displayed showing successful or unsuccessful creation of the bootstrap file. On successful creation of the bootstrap file, the System Status tab of the Configuration Tool is displayed.
39 (276)

TIBCO Spotfire Server 5.5

4 Configuration

4 5

Click the Configuration tab. Review the configuration. Verify that BASIC Database is selected in the Authentication drop-down menu and that Database is selected in the User Directory drop-down menu. Click Save configuration. The Save Configuration wizard is displayed and Database is pre-selected. Click Next. Response: The To import the configuration you must provide a comment dialog is displayed. Enter a comment, for instance Initial configuration. Click Finish. Go to the Administration tab in the Configuration Tool. In the Create new user section, type in the username and password that you would like to use for your Spotfire Administrator account Click Create. Response: The Created new user window opens. Click OK. Select the new username from the Users column and click Promote to add that user to the Administrators group.

7 8 9

10 11

4.3

Configuration Command Line Tool

To configure the Spotfire Server using the Configuration Command Line Tool run con fig.bat on Windows (available in the folder <installation dir>\tomcat\bin, which for a default Windows installation is C:\tibco\tss\5.5.0\tomcat\bin). On RPM Linux the tool is named config.sh. To execute a command, type config.sh<command>. The Configuration Command Line Tool can be used in two ways. Either execute commands one by one in a console; the section Creating a Simple Configuration using the Configuration Command Line Tool on page 42 uses this method. Or create a script containing several commands that are executed in one go, using the run command; the section Scripting a Configuration on page 51 details that procedure. Both methods can be used to configure the Spotfire Server after a simple configuration. The section below first describes how to launch a command prompt, how to move in the directories, and how to run the Configuration Command Line Tool. Next it explains how to execute the help command for the version command, and then execute the simple version command. Note: Paths and comments using spaces must be enclosed in straight quotes ("). More advanced editors may change straight quotes to smart quotes, resulting in errors when running the commands. Note: The user running the Configuration Command Line Tool needs write access to the tomcat\logs folder.

40 (276)

TIBCO Spotfire Server 5.5

4 Configuration

Executing a Configuration Command: To execute a Configuration Command, select Start > Command Prompt, or select Start, write cmd in the Search programs and files input field and select cmd.exe. Start the command prompt as an administrator when running the script. Change folder of the Configuration Command Line Tool config.bat/config.sh by first writing cd, then enter the path to the directory of the Configuration Command Line Tool (or copy the path, right-click at the cursor in the window and select Paste) and press Enter. Response: This is where you execute commands in the Command Line Configuration Tool:.

Enter config.bat(Windows) or config.sh(RPM Linux) and press Enter: Response: The Spotfire Configuration Command Line Tool is run. Since it is run without command argument, it writes the list of available commands to the console and terminates:

TIBCO Spotfire Server 5.5

41 (276)

4 Configuration

Executing Commands: To execute commands, type config followed by a command: To view the help topic on the version command, type config help version and press Enter. The tool is run executing the help command with the version parameter, and then terminates.

To run the version command, type config version and press Enter. The tool is run executing the version command, writing the version information to the console:

Many commands require parameters, like the createdefaultconfig command. Some are complex, like the bootstrap command. Both will be used in the next step, where a simple Spotfire Server configuration is created. But first section 4.3.3 lists the available commands.

4.3.1 Creating a Simple Configuration using the Configuration Command Line Tool
Integrating Spotfire Server with an existing LDAP environment? If you plan to integrate the Spotfire Server with an existing LDAP environment, proceed to Authentication and User Directory on page 53. That section describes how to create a configuration with LDAP authentication and User Directory. If you follow the instructions in this section and later the instructions in the LDAP section, the Spotfire database will be populated with both Spotfire database and LDAP accounts, where only the LDAP accounts will be possible to use. The instructions in the LDAP section do not build upon the instructions in this section. A simple configuration with Spotfire database authentication and User Directory is the most basic setup of the Spotfire Server. To create the simple configuration, use the Configuration Tool or the Configuration Command Line Tool. To achieve this, run five commands in the Configuration Command Line Tool or run a prepared script, refer to Scripting a Configuration on page 51 to use a prepared
42 (276)

TIBCO Spotfire Server 5.5

4 Configuration

script. The script provides variable definitions that can be edited and the variables are then used by the commands. Of course the commands can be run manually one after another, arguments to the commands can be seen in the script, also see section 4.3.2. To execute a Command, open a command prompt and change working directory to <installationdir>/tomcat/bin. In a default Windows installation: C:\tibco\tss\5.5.0\tom cat\bin. Type config help <command> (on RPM Linux: config.sh help <command>) to access the help for a particular command or refer to the Commands on page 177.

4.3.2 Manually Creating a Simple Configuration

To configure the TIBCO Spotfire Server and get it up and running the following is required (after the Spotfire Database has been set up, described in chapter 2, and the TIBCO Spotfire Server Installer has been run, described in chapter 3). 1 Create the connection configuration needed by the server to connect to the database with the bootstrap command. If you have already run the bootstrap command, there is no need to run it again unless you want to use different arguments. driverclass: The fully qualified class name of the JDBC driver

databaseurl: The JDBC connection URL username: The name of the database account used by the Spotfire Server to connect to the Spotfire database password: The password of the database account toolpassword: Choose a Configuration Command Line Tool password that will be used to protect the server configuration from unauthorized access and/or modification

Replace the <DRIVER CLASS>, <DATABASE URL>, <DATABASE USERNAME>, <DATABASE PASSWORD> and <CONFIGTOOLPASSWORD> with the appropriate values.
> config bootstrap driverclass="<DRIVERCLASS>" databaseurl="<DATABASEURL>" username="<DATABASEUSERNAME>" password="<DATABASEPASSWORD>" toolpassword="<CONFIGTOOLPASSWORD>"

Response: A bootstrap.xml file is created in the <installationdirectory>\tomcat\ webapps\spotfire\WEB\INF folder. See bootstrap.xml on page 158. Example:
> config bootstrap driverclass="tibcosoftwareinc.jdbc.oracle.OracleDriver" databaseurl="jdbc:tibcosoftwareinc:oracle://MyDBServer:1521;SID=XE" username= "dbuser" password="dbpwd" toolpassword="configtoolpwd"

Create a default configuration with the createdefaultconfig command:

> config createdefaultconfig

Response: A configuration.xml is created. 3 Import the configuration to the database to set it active with the importconfig command.

TIBCO Spotfire Server 5.5

43 (276)

4 Configuration

Replace the <CONFIGTOOLPASSWORD> and <DESCRIPTION>with the appropriate values.

> config importconfig toolpassword="<CONFIGTOOLPASSWORD>" comment= "<DESCRIPTION>"

Example: Import the configuration to the database

> config importconfig toolpassword="configtoolpwd" comment="Firstconfig"

Create a first user with the createuser command. This step will create an account that can be used to login to the Spotfire Server. Replace the <CONFIGTOOLPASSWORD>, <SPOTFIREADMINUSERNAME>and<SPOTFIRE ADMINPASSWORD> with the appropriate values.
> config createuser toolpassword="<CONFIGTOOLPASSWORD>" username= "<SPOTFIREADMINUSERNAME>" password="<SPOTFIREADMINPASSWORD>"

Example: Creating a new user account

> config createuser toolpassword="configtoolpwd" username="SpotfireAdmin" password="s3cr3t"

Add the first user to the Administrator group with the promoteadmin command: Replace the <CONFIG TOOL PASSWORD> and <SPOTFIRE ADMIN USERNAME> with the appropriate values.
> config promoteadmintoolpassword="<CONFIGTOOLPASSWORD>" username= "<SPOTFIREADMINUSERNAME>"

Example: Promote the new account to administrator

> config promoteadmin toolpassword="configtoolpwd" username="SpotfireAdmin"

When the Spotfire server is running, the first Administrator can create other users and add them to the Administrator group using the Administration Console.

4.3.3 Available Configuration Commands

Commands are grouped below into functional areas for easy reviewing. The command parameters to use depend on the setup and the system environment. Review applicable commands and their parameters in the alphabetically ordered reference Commands on page 177 or by using the help command in the Configuration Command Line Tool. Most configuration commands work towards the configuration.xml file. The file can be created using the exportconfig command and manually edited. The configuration is uploaded to the Spotfire database by the importconfig command, using database connection information in the bootstrap.xml file created by the bootstrap command. Some commands work directly towards the Spotfire database, like the Administration commands listed below.

44 (276)

TIBCO Spotfire Server 5.5

4 Configuration

4.3.3.1 Administration commands

These commands are used to perform basic administration tasks. All administration commands connect directly to the database.
addmember createuser deleteuser demoteadmin enableuser exportgroups exportlibrarycontent exportusers importgroups importlibrarycontent importusers listadmins listdeploymentareas listgroups listonlineservers listusers

Adds a user or group as a member of a specified group Creates a new user account Deletes a user account Revokes full administrator privileges from a user Enables or disables a user in the Spotfire Database Exports groups from the User Directory Exports content from the library Exports users from the User Directory Imports groups to the User Directory Imports content into the library Imports users to the User Directory Lists the server administrators Lists the deployment areas Lists all groups Lists all online servers Lists all users

managedeploymentareas Manages the deployment areas promoteadmin showdeployment

Assigns full administrator privileges to a user Shows the current deployment one style (DNS or NetBIOS) to the other (for all configured domains)

switchdomainnamestyle Switches the domain names for all users and groups from

updatedeployment

Updates the current deployment

TIBCO Spotfire Server 5.5

45 (276)

4 Configuration

4.3.3.2 Authentication Commands

These commands are used to configure authentication.
configauth

Configures authentication mode and default domain for use with the BASIC authentication method

configbasicdatabaseauth Configures the Spotfire Database authentication source configbasicldapauth

Configures the LDAP authentication source for use with the BASIC authentication method with the BASIC authentication method

configbasicwindowsauth Configures the Windows NT authentication source for use configclientcertauth configdelegateauth

Configures the CLIENT_CERT authentication method Configures the Delegate authentication method

configimpersonationauth Configures the Impersonation authentication method configkerberosauth configntlmauth configpostauthfilter listauthmode listauthconfig listntlmauth listpostauthfilter setauthmode showbasicldapauth

Configures the authentication service used with the Kerberos authentication method Configures the authentication service used with the NTLM authentication method Configures the Post Authentication Filter Displays the currently configured authentication mode Displays the current authentication configuration Displays the NTLM authentication service configuration Displays the current Post Authentication Filter configuration Sets the authentication mode (deprecated, replaced by config-auth) Shows the LDAP authentication source for use with the BASIC authentication method

4.3.3.3 Information Services Commands

These commands are used to configure Information Services.
adddstemplate clearjoindb createjoindb

Adds a new data source template Clears the default join database configuration Configures the default join database

46 (276)

TIBCO Spotfire Server 5.5

4 Configuration

exportdstemplate listdstemplate modifydstemplate removedstemplate showjoindatabase

Exports the definition of a data source template Lists the data source templates Modifies a data source template Removes a data source template Shows the configured default join database

4.3.3.4 JAAS Commands

These commands are used to manage JAAS configurations. The testjaasconfig command connects to the database in a read operation.
importjaasconfig listjaasconfig removejaasconfig testjaasconfig

Imports new JAAS application configurations into the server configuration Lists the JAAS application configurations Removes the specified JAAS application configurations from the server configuration Tests a JAAS application configuration

4.3.3.5 Client Configuration Commands

These commands are used to configure clients connecting to the Spotfire Server.
configlogindialog

Configures the client login dialog behavior

4.3.3.6 Monitoring Commands

These commands are used to configure and administrate JMX access to the monitoring component. All monitoring commands connect directly to the database except for con figjmx.
configactionlogdatabase Configures the user action database logger logger configactionlogger

Configures the user action logger.

configactionlogwebservi Configures the action log web service ce configjmx

Configures the JMX RMI connector

TIBCO Spotfire Server 5.5

47 (276)

4 Configuration

createjmxuser deletejmxuser listjmxusers

Creates a new JMX user account Deletes a JMX user Lists all JMX users

4.3.3.7 LDAP Commands

These commands are used to manage LDAP configurations for both authentication and the User Directory.
configldapgroupsync createldapconfig listldapconfig removeldapconfig updateldapconfig

Configures group synchronization for an LDAP configuration Creates a new LDAP configuration to be used for authentication and/or the User Directory LDAP provider Displays LDAP configurations Removes LDAP configurations Updates LDAP configurations

4.3.3.8 Library Commands

These commands are used to configure the Spotfire Library.
configimportexportdirect Configures the library import/export directory ory showimportexportdirect Shows the library import/export directory ory

4.3.3.9 Server Configuration Commands

These commands are used to perform basic server configuration tasks. Server configuration commands connect directly to the database except for createdefaultconfig.
createdefaultconfig exportconfig importconfig listconfigs setconfig

Creates a new server configuration file containing the default configuration Exports a server configuration from the server database to the current working directory as a configuration.xml file Imports a server configuration from a file to the server database Lists all available server configurations Sets the current server configuration

48 (276)

TIBCO Spotfire Server 5.5

4 Configuration

setrestartpolicy showconfighistory showrestartpolicy

Sets the server restart policy Shows the configuration history Shows the server restart policy

4.3.3.10 Server Database Commands

These commands are used to manage the server database connection pool. Server database commands connect directly to the database except for bootstrap, which can connect to the database to test the bootstrap configuration but does not change it.
bootstrap modifydbconfig setdbconfig

Creates database connection information and stores it in the bootstrap.xml file. See bootstrap.xml on page 158. Modifies the common database connection configuration Sets the common database connection configuration

4.3.3.11 User Directory Commands

These commands are used to configure the User Directory.
configldapuserdir configuserdir configwindowsuserdir listldapuserdirconfig listuserdirmode listuserdirconfig

Configures the LDAP User Directory mode Configures the User Directory Configures the Windows User Directory mode Lists the configuration for the User Directory LDAP mode Lists the currently configured User Directory mode Lists the current User Directory configuration mode

listwindowsuserdirconfig Lists the configuration for the User Directory Window NT setuserdirmode

Sets the User Directory mode (deprecated, replaced by config-userdir)

TIBCO Spotfire Server 5.5

49 (276)

4 Configuration

4.3.3.12 Various Commands

configattachmentmanage This command is used to configure the Attachment r Manager which handles data transfer to and from the

TIBCO Spotfire Server

4.3.3.13 Other Commands

help run version

Displays the help overview or a specific help topic Runs a configuration script Displays the current version of the server

4.4

Script Language
A script language is available. Create and run a script to invoke multiple commands in one go.
#

If a hash is the first character on a line, the line is a comment Example: # This is a comment that describes the next section. Defines a variable: The variable name and the value must be separated with an equal character (=) Example: set PASSWORD = "abc123" Substitutes the dollar sign and curly braces with the variable value: If there is no matching variable, there is no substitution Example: --tool-password="${PASSWORD}" The logical line continues on the next line Example: bootstrap --no-prompt --driver-class="${DB_DRIVER}" \ --database-url="${DB_URL}" Writes to console Example: echo This message will be posted echo Empty rows are allowed

set

${Variable}

echo

Note: Paths and comments using spaces must be enclosed in straight quotes ("). More advanced editors may change straight quotes to smart quotes, resulting in errors when running the commands.

50 (276)

TIBCO Spotfire Server 5.5

4 Configuration

4.4.1 Scripting a Configuration

You can create and run scripts of your own and two prepared scripts are provided in the <installationdir>/tomcat/bin folder. The simpleconfig.txt file sets up Spotfire Database authentication and User Directory and the simpleconfigldap.txt sets up LDAP authentication and User Directory. Example: The simpleconfig.txt file is shown below, it is divided into three sections: The first lines describe how the script is executed using the run command

Then a section of variables follows, variables that are used by the commands Finally the sections containing the commands follow

# Run this script from the command-line using the following command: # config run simple-config.txt # Before using this script you need to set the variables below: set DB_DRIVER = "tibcosoftwareinc.jdbc.oracle.OracleDriver" set DB_URL = "jdbc:tibcosoftwareinc:oracle://<server>:<port>;SID=\ <SID>" #set DB_DRIVER = "tibcosoftwareinc.jdbc.sqlserver.SQLServerDriver" #set DB_URL = "jdbc:tibcosoftwareinc:sqlserver:// <server>:<port>;DatabaseName=<database name>" set DB_USER = "<db username>" set DB_PASSWORD = "<db password>" set CONFIG_TOOL_PASSWORD = "<config tool password>" set ADMIN_USER = "<admin username>" set ADMIN_PASSWORD = "<admin password>" echo Creating the database connection configuration bootstrap --no-prompt --driver-class="${DB_DRIVER}" --database-url=\ "${DB_URL}" \ --username="${DB_USER}" --password="${DB_PASSWORD}" --tool-password="${CONFIG_TOOL_PASSWORD}" echo echo Creating the default configuration create-default-config echo echo Importing the configuration import-config --tool-password="${CONFIG_TOOL_PASSWORD}" --comment=\ "First config" echo echo Creating the '${ADMIN_USER}' user to become administrator create-user --tool-password="${CONFIG_TOOL_PASSWORD}" --username=\ "${ADMIN_USER}" --password="${ADMIN_PASSWORD}" echo echo Promoting the user '${ADMIN_USER}' to administrator promote-admin --tool-password="${CONFIG_TOOL_PASSWORD}" --username=\ "${ADMIN_USER}" echo
TIBCO Spotfire Server 5.5

51 (276)

4 Configuration

Edit the script to make it work in your environment: Open simpleconfig.txt in a text editor and edit the variables: If you use SQL Server, comment out the Oracle variables (#) and uncomment the SQL Server variables (remove #): For DB_URL, provide the specific values indicated by angle brackets. The DB_USER and DB_PASSWORD used in the create_databases.bat script (described in Prepare the Database on page 17). The DB_USER and DB_PASSWORD values are the Spotfire database username and password. The CONFIG_TOOL_PASSWORD. Choose a Configuration Command Line Tool password that will be used to protect the server configuration from unauthorized access and/or modification. The ADMIN_USER and ADMIN_PASSWORD. First create the user, and then include the user in the group of Administrators (promote the user to the Administrator). Save the script. If you do not want to overwrite the existing script, use another name. To run the script: Start a command prompt and navigate to <installationdir>\tomcat\bin. Type config run simpleconfig.txt and press Enter. The script executes and the Spotfire Server receives a basic configuration. Note that the tool provides feedback when running the script. In this case a script has already been run: The tool is conservative and does not overwrite the bootstrap.xml or configuration.xml located in the <installationdir>/tomcat/bin unless the force flag is used. The AdminUser is created and promoted to Administrator: This user did not exist.

1 2

It is recommended to manually remove the configuration.xml when you are done. Note: Do not remove bootstrap.xml. It is required to start and run the server. See bootstrap.xml on page 158. Note: The simpleconfig.txtfile contains sensitive information. To close the command prompt, type exit and press Enter or close the window.

52 (276)

TIBCO Spotfire Server 5.5

4 Configuration

4.5

Authentication and User Directory

4.5.1 Authentication Methods

The Spotfire Server supports several authentication methods:

Authentication methods based on usernames and password are described in Username and Password Authentication Methods on page 55. Single sign-on authentication methods like NTLM, Kerberos and X.509 Client Certificates are described in Single Sign-On Authentication Methods on page 58.

4.5.2 User Directory

The Spotfire Server stores the names of the users, and optionally also their passwords, in its User Directory. In the User Directory, it is possible to organize the users in groups. The user and group information can later be used to assign permissions, licenses, preferences etc. to the different resources available within the Spotfire system. To integrate existing IT systems, the User Directory can use external user-handling systems. Administrators do not have to replicate user lists or group hierarchies from their existing environments in the Spotfire Server. The external directory is usually an LDAP directory, such as Windows AD, but the Spotfire Server also offers a legacy Windows NT Domain integration, where the user information is collected from Windows NT domain controllers. Starting with version 5.0, the TIBCO Spotfire Server only accesses the external directories during its periodical synchronization of the User Directory, though password verification will require a connection, as well as checking for new users. The TIBCO Spotfire Server will periodically refresh the information about the users and the groups with the current information from the external directories. For a comprehensive list of user directory modes, and how they can be combined with different Authentication methods, See User Directory Modes on page 77.

TIBCO Spotfire Server 5.5

53 (276)

4 Configuration

4.5.3 Authentication and Post-Authentication Filter

When users log in to the Spotfire Server, their identities are verified in the following steps: 1 The credentials are validated in order for the Spotfire Server to confirm the identity of the user. Typical credentials are usernames and passwords, NTLM tokens, Kerberos tickets or X.509 client certificates.

If the Spotfire Server is configured to store both usernames and hashed passwords in its database, the server can validate the user-supplied credentials by itself. If the Spotfire Server is set up to integrate with an external directory, the validation responsibility is delegated to this system. Such a system can for instance be an LDAP directory or a Windows domain controller.

When the user identity is established, an extra post-authentication check is performed by the TIBCO Spotfire Server's Post-Authentication Filter. The filter has two built-in modes: blocking and auto-creating:

Blocking mode: The filter simply blocks all users that are not already present in the server's User Directory. Auto-creating mode: The filter automatically creates new accounts for any user that logs into the server for the first time. This mode is only valid if Spotfire database mode is configured.

The blocking mode is the default mode. When it is used with a User Directory in LDAP/Active Directory mode, it automatically transforms to the domain name of the authenticated user to match the configured domain name style. The auto-creating mode is typically applied when using an LDAP directory or X.509 certificates for authentication together with the User Directory set up in database mode. The Post-Authentication Filter will create users with their external domain names, even though the User Directory is in database mode, unless the collapse domains configuration property is enabled. This makes it possible to later switch to LDAP or Windows NT mode. If the collapse domains configuration property is enabled, the users will be created within the internal SPOTFIRE domain and it will not be possible to later switch to LDAP or Windows NT mode. It is also possible to use the Spotfire Server's API to create a custom Post-Authentication Filter to perform additional validation. This filter must be installed in the <installa tion dir>/tomcat/webapps/spotfire/WEBINF/lib directory on all servers. It is enabled using the config-post-auth-filter on page 204. If a custom filter is used, it will be combined with the built-in filter, meaning that the filters will work together. This is a change from previous releases where the custom filter had to be used instead of a built-in filter. When the user identity is both confirmed (using the credentials) and filtered (meaning that the user exists in the User Directory), an authority check is made to decide whether or not the user is allowed to access the requested resource and what the user can do with regard to licenses etc.

54 (276)

TIBCO Spotfire Server 5.5

4 Configuration

4.6

Username and Password Authentication Methods

When users start a Spotfire client, they are presented with a login dialog where they select which Spotfire Server to connect to. If that server uses a username and password based authentication method, the users are also prompted for username and password. The username and password are then sent to the Spotfire Server (over the HTTP BASIC protocol). The username and password authentication methods are sometimes referred to as BASIC authentication methods. The credentials are not encrypted then they are transferred unless the server uses TLS/SSL. and the information can easily be collected by other eavesdropping computers on the network. To use any username and password authentication method in a safe manner, make sure to also enable TLS/SSL to safely transfer the username and the password to the Spotfire Server over the encrypting HTTPS protocol. The username and password can be validated using:

Spotfire database LDAP Directory (for example Active Directory) Windows NT Domain (Legacy, use only if you cannot use LDAP) Custom JAAS

For all methods, entries are created in the Spotfire database. When using an external authentication method, appropriate information is copied to the Spotfire database.

4.6.1 Authentication towards the Spotfire Database

This authentication method requires that the User Directory is configured for Spotfire database. The database will store the names and password hashes of all users, and an administrator will have to create all user accounts in advance. This is the default behavior, and no configuration is needed for this authentication method. This is a configuration that is easy and fast to set up and it is recommended for small sites. To create a lot of users at once, export the users from an external system and imported to the Spotfire Database using the Administration Manager.

4.6.2 Authentication towards LDAP

This authentication method integrates with an existing LDAP directory and delegates the actual authentication responsibility to its configured LDAP servers. The result is that only users with valid accounts in the LDAP directory can log in to the Spotfire Server. This setup is recommended for all larger sites. It can be combined with both Spotfire database User Directory and LDAP User Directory. It is recommended to combine the LDAP authentication method with an LDAP User Directory mode. However, in some cases, for example where the LDAP directory contains a very large number of users that are not divided into convenient sub-units (contexts), combining the LDAP authentication method with a Spotfire database User
TIBCO Spotfire Server 5.5

55 (276)

4 Configuration

Directory will reduce the set of users tracked within the Spotfire Server. Only the users that are logging into the Spotfire Server will be included. This makes the Spotfire Server's User Directory easier to manage and survey. When combining it with a Spotfire database User Directory configuration, the users shall be automatically added to the User Directory and consequently the Post-Authentication Filter must be configured in auto-creating mode. When combining it with an LDAP User Directory mode, the default setting of the Post-Authentication Filter, blocking mode, is already correct. The Spotfire Server supports the following LDAP servers:

Microsoft Active Directory Oracle Directory Server, Sun Java System Directory Server, Sun ONE Directory Server, iPlanet Directory Server, Netscape Directory Server

If your site is using another type of LDAP server, the Spotfire Server may be able to use a custom LDAP configuration, which is slightly more advanced to configure. Note: When the Spotfire Server is authenticating towards a Microsoft Active Directory server, it will automatically use the Fast Bind Control (also known as Concurrent Bind Control) option to minimize the consumed resources on the LDAP server.

4.6.3 Configuring SASL Authentication for LDAP

DIGEST-MD5 and GSSAPI are SASL (Simple Authentication Socket Layer) mechanisms. These are used for secure authentication of the Spotfire Server when it is connecting to LDAP Servers. SASL prevent clear text passwords from being transmitted over the network.

4.6.3.1 DIGEST-MD5
When configuring SASL authentication with DIGEST-MD5 in an Active Directory environment, the distinguished name (DN) does not work for authentication and the userPrincipalName attribute must be used instead. The authenticationattribute option should be set to userPrincipalName and the usernameattribute option should be set to sAMAccountName, which is the default value for an Active Directory LDAP configuration. When setting up SASL with DIGEST-MD5 in an Active Directory environment, all accounts must use reversible encryption for their passwords. This is typically not the default setting for Active Directory.

4.6.3.2 GSSAPI
These instructions apply for Active Directory LDAP configurations. The Spotfire Server does not support GSSAPI for other LDAP alternatives. The GSSAPI authentication mechanism provides secure authentication even over un-secure networks since it uses the Kerberos protocol for authentication. Passwords

56 (276)

TIBCO Spotfire Server 5.5

4 Configuration

are not sent in clear text across the network even if using un-encrypted HTTP, for information about Kerberos in general, see Kerberos Authentication on page 64.

Configure the Spotfire Server for GSSAPI Authentication of LDAP Preparations: Make sure you have a fully working Active Directory LDAP configuration using clear-text password authentication (also known as simple authentication mechanism). This configuration is created using the Configuration Tool or the Configuration Command Line Tool.

Save this fully working Active Directory LDAP configuration to file. Note the LDAP configuration's ID.

Make sure that you have a fully working krb5.conf file. The content of the krb5.conf file shall be the same as when setting up the Spotfire Server for Kerberos authentication. See Configure Kerberos for Java: on page 68. Note: Make sure to stop the entire service/Java process before installing the file. It is not sufficient that the restart-policy is set automatic force or automatic on idle. If the krb5.conf file is modified after the Spotfire Server has been started, a restart of the Spotfire Server process is required for the modifications to have effect. Procedure:

1 2 3 4 5

Stop the Spotfire Server, See Start and Stop the Spotfire Server on page 102. Copy the fully working krb5.conf file to the <instdir>/jdk/jre/lib/security directory on each Spotfire Server in the cluster. Start the Configuration Tool and provide the Tool Password, See Configuration Tool on page 34. Go to the LDAP Configuration Panel. Update the LDAP username so that it is a proper Kerberos principal name. Usually it is sufficient to add the name of the account's Windows domain written in upper-case letters. Sometimes its also necessary to include the Windows domain name as well. Using a name based on a distinguished name (DN) or including a NetBIOS domain name does not work when using GSSAPI. Examples of correct names: "ldapsvc@ RESEARCH.EXAMPLE.COM" and "[email protected]@ RESEARCH.EXAMPLE.COM". Select the specific LDAP configuration to be GSSAPI enabled and expand the Advanced settings. Set the security-authentication configuration property to GSSAPI. Set the authentication-attribute to sAMAccountName or userPrincipalName (select what works best for your configuration). The default value is empty.

6 7 8

TIBCO Spotfire Server 5.5

57 (276)

4 Configuration

Note: If the krb5.conf file contains more than one Kerberos realm, the authentication-attribute must be set to "userPrincipalName". 9 10 11 Add a custom property with the key kerberos.login.context.name and the value SpotfireGSSAPI. Save the configuration to the Spotfire database by clicking Save configuration. Start the Spotfire Server, See Start and Stop the Spotfire Server on page 102. Procedure steps related to LDAP configurations need to be performed for each LDAP catalogue that shall have GSSAPI enabled. For multiple LDAP configurations, repeat these steps for each configuration.

4.6.4 Authentication towards Windows NT Domain (legacy)

With this authentication method, user authentication is delegated to Windows NT domain controllers. To be able to use this method, the Spotfire Server must be installed on a machine running Windows and you must have a working Windows NT 4 Server Domain Controller or a Windows Server 2000 (or later) Domain Controller running in Mixed Mode. This is a legacy solution that should only be used if LDAP cannot be used. Just like the LDAP authentication method, the Windows NT Domain authentication method can be combined with a User Directory in either Windows NT Domain mode or in Spotfire database mode. When combining this authentication method with a Spotfire database User Directory mode, the Post-Authentication Filter must be configured in auto-creating mode, so that the users will be automatically added to the User Directory. When combining it with a Windows NT Domain User Directory mode, the default blocking Post-Authentication Filter is already correct.

4.6.5 Authentication towards a Custom JAAS Module

All authentication methods described above are implemented as Java Authentication and Authorization Service (JAAS) modules. Spotfire also supports third-party JAAS modules. You may therefore use a custom JAAS module, provided that it validates username and password authentication and that it uses JAAS NameCallback and Pass wordCallback objects for collecting the usernames and passwords. When using a custom JAAS module, you must place the jar file in the <installation dir>/tomcat/webapps/spotfire/WEBINF/lib directory on all Spotfire Servers. Consult the JAAS Reference Guide for more information about JAAS.

58 (276)

TIBCO Spotfire Server 5.5

4 Configuration

4.7

Single Sign-On Authentication Methods

The Spotfire Server is capable of integrating with some single sign-on systems used in enterprise environments. A single sign-on system can be defined as an authentication system that provides access to many resources once the user is initially authenticated. The Spotfire Server can use the NTLM or Kerberos single sign-on authentication methods, where the identity information stored within the users current Windows session is reused to authenticate the user on the server. Thus, when using these authentication methods, the user is never prompted for username or password when logging in to the Spotfire Server. The Kerberos and NTLM authentication methods are commonly referred to as Windows Integrated Authentication. The Spotfire Server can also authenticate users based on X.509 certificates. This requires the server to be configured for mutual SSL, meaning HTTPS with X.509 client certificates.

4.7.1 NTLM Authentication

The NTLM authentication method reuses the identity information associated with the user's current Windows session that is created when the user initially logs in to Windows. When both the client computer and the server computer belong to the same Windows domain or two separate Windows domains with established trust between them, this can provide a single sign-on experience. If the client computer belongs to a separate Windows domain (without trust established to the server computers domain), the current Windows session is not valid in the Windows domain of the server computer and the user will be prompted for username and password. The user must then enter username and password of a valid account that belongs to the Windows domain of the server computer. It is not possible to delegate NTLM authentication, the Spotfire Server can not reuse the authentication credentials presented by the client, for example when authenticating against an Information Services data source that also uses NTLM. If you need such functionality, you must use Kerberos instead. Upgrading to 5.0 or later: TIBCO Spotfire Server supports NTLMv2 since version 3.2. The older NTLMv1 authentication mechanism was deprecated in version 4.5 and has now been removed. The instructions below explain how to set up the newer NTLMv2 authentication mechanism. The NTLM authentication method needs to be combined with a User Directory in either:

LDAP mode, recommended, see User Directory in LDAP Mode on page 78. Spotfire database mode, provided that the default Post-Authentication Filter is configured in auto-creating mode, see User Directory in Spotfire Database Mode on page 77.

The following instructions assume that either of these combinations is already fully working.
TIBCO Spotfire Server 5.5

59 (276)

4 Configuration

When using the NTLM authentication method, the User Directory is typically configured for the NetBIOS domain name style. Setting up NTLM authentication involves two steps: 1 Creating a computer service account in your Windows Domain You must create a computer service account in your Windows Domain. A Visual Basic script, SetupWizard.vbs(developed by IOPLEX Software) is distributed with the Spotfire Server and will perform this task. The script must be run on a Windows machine, but does not have to be run on the same machine as the server is installed on. If you are unable to run this script, or prefer to create the account manually, make sure to create a computer account. A user account will not work. Reusing an existing computer account will not work. See Creating a Computer Account Manually on page 61. 2 Configuring NTLM authentication using configuration commands. Note: If you have more than one Spotfire Server in the cluster, you must also perform additional steps on each Spotfire Server.

To create a computer service account in your Windows domain: You must be logged into your Windows domain as a member of the group Account Operators or Administrators to run the SetupWizard.vbs script.

Double click on the setupwizard.vbs script located in the directory <installationdir>/ tomcat/bin. If the server is installed on a Linux or Solaris machine, the script has to be copied to a Windows machine first. In the Domain Controller Hostname panel, enter the hostname of one of your domain controllers. Click OK. In the Account Name panel, enter the short name of the computer account to be created. The short name must not exceed 15 characters. Click OK. In the Distinguished Name panel, enter a distinguished name for the account to be created. A distinguished name based on the short name entered in the previous panel is suggested. You should edit this to match your Windows domain, with regards to parameters such as in which Organizational Units (OU) the account should be placed. Click OK. In the Account Password panel, enter a password for the account to be created. Click OK. A dialog will show with text indicating if the tool was successful or not. Click OK. Note: If the tool was unsuccessful, you should make sure that the logged in user has the required permissions to create accounts in the Windows Domain, and that the Domain Controller can be reached.

2 3 4

5 6

60 (276)

TIBCO Spotfire Server 5.5

4 Configuration

The file SetupWizard.txt, created by the tool in the folder where the tool is located, will open. If it does not, open it manually. The information is required to run the NTLM authentication configuration commands. File example:
# Generated by the Jespa Setup Wizard from IOPLEX Software on 2011-04-07 jespa.bindstr = dc.example.research.com jespa.dns.servers = 192.168.0.1 jespa.dns.site = Default-First-Site-Name jespa.service.acctname = [email protected] jespa.service.password = Pa33w0rd

Creating a Computer Account Manually If you prefer to create the computer account manually, you should do so using the Microsoft Management Console snap-in Domain Users and Computers. Refer to Microsoft documentation for details on how to use this tool. 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 <installation dir>/tomcat/bin there is a VBS script called SetComputerPassword.vbs. Run this script from the command line with the account name and password as arguments to the command. Note: The SetComputerPassword.vbsfile can only be executed on a Windows machine. The script must be copied to a Windows machine, but does not have to be run on the same machine as the server is installed on. Example:
SetComputerPassword.vbs [email protected] Pa33w0rd

To configure NTLM for a single server Use the Configuration tool or

1 2

Use the command configntlmauth (page 201) and listntlmauth (page 238) to configure NTLM authentication. Use the setauthmode (page 249), import the configuration and restart the server to activate the NTLM SSO authentication method. To run these commands, you need some of the specific information described below.
Server (optional) The name of the server instance to which the specified configuration options belong. If no server name is specified, then all parameters will be shared, applying to all servers in the cluster. It is common to use server-specific values for the accountname, password and localhost NetBIOSname configuration options.

TIBCO Spotfire Server 5.5

61 (276)

4 Configuration

Accountname (required)

Specifies the fully qualified name of the Active Directory computer account that is to be used by the NTLM authentication service. This account must be a proper computer account, created solely for the purpose of running the NTLM authentication service. It can neither be an ordinary user account, nor an account of an existing computer. Note that the local part of an Active Directory computer account name always ends with a dollar sign, for instance: [email protected]. The local part of the account name (excluding the dollar sign) must not exceed 15 characters. Example: [email protected]

Password (required)

Specifies the password for the computer account used by the NTLM authentication service.

DNSdomainname The DNS name of the Windows domain to which the Spotfire Servers (optional) computer belongs. The specified domain name will automatically be resolved into domain controller hostnames. As an alternative to specifying a DNS domain name, it is also possible to specify a domain controller hostname directly. It is recommended to use the DNS domain name option, since you then automatically get the benefits of fail-over and load-balancing, provided that you have more than one domain controller. The DNS domain name and domain controller arguments are mutually exclusive. Example: research.example.com Domaincontroller (optional) The DNS hostname of an Active Directory domain controller. It is recommended that the DNS domain name option is to be used instead, since that option gives the benefits of fail-over and load-balancing. The domain controller and DNS domain name arguments are mutually exclusive. Example: dc01.research.example.com DNSservers (optional) A comma-separated list of IP addresses of the DNS servers associated with the Windows domain. When no DNS servers are specified, the server will fall back to use the server computers default DNS server configuration. Example: 192.168.1.1,192.168.1.2 ADsite (optional) Specifies the Active Directory site where the Spotfire system is located. Specifying an Active Directory site can potentially increase performance, since the NTLM authentication service will then only communicate with the local Windows domain controllers. Example:VIENNA DNScacheTTL (optional) Specifies how long (in milliseconds) name server lookups should be cached. The default value is 5000 ms.

62 (276)

TIBCO Spotfire Server 5.5

4 Configuration

LocalhostNetBIOS Specifies the NetBIOS name, used by a server to identify its name connection to the domain controller. The default value is derived from the account name option. This option is only necessary to specify when (optional) there is more than one server in the cluster. Since a domain controller only allows one connection per NetBIOS name, a cluster with multiple servers must either use separate NTLM accounts for each server or explicitly specify unique localhost NetBIOS names for the servers. The localhost NETBIOS name must not exceed 15 characters in length. Example: ntlmsvcserver1 (for server1.research.example.com) ConnectionID headername (optional) This parameter specifies the name of an HTTP header containing unique connection IDs in environments where the server is located behind some kind of proxy or load-balancer that does not properly provide the server with the client's IP address. The specified HTTP header must contain unique connection IDs for each client connection and is thus typically based on the clients IP address together with the connection's port number on the client side.

To configure NTLM for a cluster with multiple servers To set up NTLM for a cluster with multiple servers, start with configuring the options common to all servers in the cluster. This is performed according to the instructions in To configure NTLM for a single server on page 61, with the following modifications. This step involves specifying a DNSdomainname (recommended) or a domaincontrol ler (not recommended) and possibly also an ADsite name. The accountname and pass word options must be left out at this point (will be specified later). It is also very important that the server argument is not specified at this stage. The common NTLM configuration now needs to be completed with account information for each Spotfire Server in the cluster. When a server logs in to the domain controller, its identity is based on the name of the computer account it uses for the connection. The resulting name is known as a localhost NetBIOS name. Since a domain controller only allows one connection per localhost NetBIOS name, multiple servers typically cannot login using the same computer account. Thus, each server ideally uses its own NTLM account. Note: Sometimes, like when running two servers on the same computer, it happens to be possible to actually share the NTLM account by explicitly specifying individual localhost NetBIOS names that are used instead of the name derived from the NTLM account.

If separate NTLM accounts are to be used, then use the accountname and password options to specify the server's own NTLM account. If a shared NTLM account is to be used, specify the accountname and password for the shared account, as well as a unique localhostNetBIOSname. The localhost NetBIOS names must not exceed 15 characters.

When the decision has been made whether to use individual NTLM accounts or share an NTLM account by explicitly specifying localhost NetBIOS names, the command
TIBCO Spotfire Server 5.5

63 (276)

4 Configuration

configntlmauth is run again, once for each server in the cluster. The command will update the Spotfire Server configuration with the cluster servers specific configuration options. This time, the server argument must be specified so that it reflects the server name, as defined in the servers bootstrap.xml file.

4.7.2 Kerberos Authentication

The picture illustrates a simplified overview of Kerberos Authentication with delegation. Kerberos is a single sign-on protocol that allows for secure authentication even over unsecure networks. The Kerberos protocol uses tickets for authentication instead of usernames and passwords. The tickets are issued by a centralized Kerberos server and contains information that only the intended target of the ticket can decrypt. In Microsoft Windows environments, the domain controllers act as Kerberos servers, and every user automatically signs in to Kerberos when logging in to the Windows desktop. Kerberos can be a bit hard to set up, but once it is fully working you have a very secure authentication system with the benefits of single sign-on. Prerequisites

Windows Domain Controllers running Windows Server 2003 SP1 or later. A computer with the MicrosoftActiveDirectoryUsersandComputers MMC snap-in. A computer with the MicrosoftSupportTools installed. A domain administrator account or a user account which is a member of the built in AccountOperators domain group, or any account with similar permissions. Windows Domain accounts for all Spotfire users.

64 (276)

TIBCO Spotfire Server 5.5

4 Configuration

A fully working User Directory in place, either in LDAP mode (recommended) or

Spotfire database mode, provided that the built-in Post-Authentication Filter is autocreating

It us usually a good idea to first create a working setup where the server uses Basic/ LDAP authentication and a User Directory in LDAP mode and then proceed with switching from Basic/LDAP to Kerberos.

4.7.2.1 Configuration Instructions

The following instructions are required to configure the Spotfire Server for the Kerberos authentication method. As a Domain Administrator: 1 Create a Kerberos service account: In this step the Kerberos service account is created. The following examples will assume that the account's name is spotsvc. Logged in as a domain administrator or a user which is a member of the built in Account Operators domain group, launch the Active Directory Users and Computers MMC snap-in and create a normal user account with the following properties: Use the same identifier in the Fullname and Userlogonname(preWindows2000) fields and make sure to use only lower case characters and that there are no spaces in these fields. Select the Passwordneverexpires option. Clear the Usermustchangepasswordatnextlogon option. If Kerberos unconstrained delegation is to be used for Information Services data sources, the account option Accountistrustedfordelegation must also be selected. Kerberos constrained delegation can also be used for Information Services data sources, but is set up on a service-by-service basis and is not described here. Register Service Principal Names:

While still logged in as a domain administrator or as a user which is a member of the built in AccountOperators domain group, use the setspn.exe command-line tool to register two Service Principal Names (SPNs) for the Kerberos service account. The setspn.exe command-line tool is a part of the Microsoft Support Tools package which is typically installed on domain controllers. The Support Tools can also be downloaded from Microsoft's web page. The setspn.exe tool for Windows Server 2008 or later has been improved with extra argument checking to prevent that no duplicate Service Principal Names are created. If you use the improved version of the setspn.exe tool, then execute the following two commands to register the Service Principal Names:
> setspn S HTTP/<fully qualified hostname>[:<port>] <service account name> > setspn S HTTP/<hostname>[:<port>] <service account name>
TIBCO Spotfire Server 5.5

65 (276)

4 Configuration

If you are using the setspn.exe tool for Windows Server 2003 or earlier, the extra argument checking is not supported. Instead, execute the following two commands to register the Service Principal Names:
> setspn A HTTP/<fully qualified hostname>[:<port>] <service account name> > setspn A HTTP/<hostname>[:<port>] <service account name>

Note: Internet Explorer 6 excludes the port from the commands above. If it is necessary to set another port than default 80, a hotfix from Microsoft is needed. This hotfix is already included in later versions of Internet Explorer, but the registry setting needs to be enabled. See Microsofts homepage for more information. Note: If the above mentioned hotfix is enabled, the port number will be included in all SPNs for all Kerberos-enabled applications accessed from this machine as well. Review and make sure all other applications are still working if you enable the hotfix. Note: It is not recommended to enable the hotfix. Note: It is recommended not to have multiple Kerberos-enabled HTTP services on one machine. Replace the <fullyqualifiedhostname>, <serviceaccountname>, <hostname> and <port> with the appropriate values. Note: It is vital to note that all values are case sensitive.

fullyqualifiedhostname: The fully qualified DNS hostname of the computer

hosting the Spotfire Server (written in lower case)

hostname: The short DNS hostname, without domain suffix, of the computer

hosting the Spotfire Server (written in lower case)

serviceaccountname: The userloginname of the previously created Kerberos service account (written in lower case) port: The TCP port number that the Spotfire Server is listening on

Note: You must use the name of an A record for the Spotfire Server. A CNAME record will not work. Note: Avoid explicitly specifying the port number if the Spotfire Server is using the default HTTP port 80. Example : Registering Service Principal Names for the spotsvc Kerberos service account to be used by a Spotfire Server installed on the spotfireserver.research.example .com computer and listening on the default HTTP port 80 or the default HTTPS port 443:
> setspn A HTTP/spotfireserver.research.example.com spotsvc > setspn A HTTP/spotfireserver spotsvc

This will create these two Service Principal Names:

HTTP/spotfireserver.research.example.com HTTP/spotfireserver

66 (276)

TIBCO Spotfire Server 5.5

4 Configuration

Example : Registering Service Principal Names for the spotsvc Kerberos service account to be used by a Spotfire Server installed on the spotfireserver.research.example .com computer and listening on the non-default HTTP port 8080:
> setspn A HTTP/spotfireserver.research.example.com:8080 spotsvc > setspn A HTTP/spotfireserver:8080spotsvc

This will create two SPNs:

HTTP/spotfireserver.research.example.com:8080 HTTP/spotfireserver:8080

To list the resulting Service Principal Names for a Kerberos service account, you can execute the following command:
> setspn L <service account name>

Example: Verifying Service Principal Names for the spotsvc Kerberos service account
>setspnLspotsvc

Create a keytab file for the Kerberos service account: While still logged in as a domain administrator or as a user which is a member of the built in AccountOperators domain group, execute the following command:
> ktpass /princ HTTP/<fully qualified hostname> [:<port>]@<realm> /ptype krb5_nt_principal /crypto rc4hmacnt /mapuser <service account name> /out spotfire.keytab kvno0/pass *

Replace the <fully qualified hostname>, <port>, <realm>, and <service account name> with the appropriate values. Note: It is vital to note that all values are case sensitive.

fullyqualifiedhostname: The fully qualified DNS hostname of the computer

hosting the Spotfire Server, which must exactly match the fully qualified hostname used when registering the SPNs (written in lower case)

port: The TCP port number that the Spotfire Server is listening on (only specified if the port number was explicitly included in the registered SPNs) realm: The name of the Kerberos realm, which is the DNS domain name written in upper case serviceaccountname: The userloginname of the service account with the registered SPNs (written in lower case)

The tool will prompt for the password of the service account. Enter the same password as when creating the service account. It is not critical to use the name spotfire.keytab for the keytab file. However, the remaining instructions will assume that this is the name of the keytab file.

TIBCO Spotfire Server 5.5

67 (276)

4 Configuration

Note: If you ever change the password of the Kerberos service account in the future, you must re-create the keytab file. Note: Older versions of the ktpass.exe tool will fail to create the keytab file when it is not being run on an actual domain controller. Example : Creating a keytab file for the spotsvc Kerberos service account in the research.example.com domain for the Spotfire Server listening on the default HTTP port 80 on the spotserver.research.example.com computer:
>ktpass/princHTTP/[email protected]/ ptypekrb5_nt_principal/cryptorc4hmacnt/mapuserspotsvc/outspotfire.keytabkvno 0/pass*

Example : Creating a keytab file for the spotsvc Kerberos service account in the research.example.com domain for the Spotfire Server listening on the HTTP port 8080 on the spotserver.research.example.com computer:
> ktpass /princ HTTP/spotfireserver.research.example.com:8080@ RESEARCH.EXAMPLE.COM /ptype krb5_nt_principal /crypto rc4hmacnt /mapuser spotsvc /out spotfire.keytab kvno0/pass *

On the Spotfire Server: 4 Copy the Kerberos service accounts keytab file to the Spotfire Server: Copy the spotfire.keytab file to the directory <installation dir>\jdk\jre\lib\security (Windows) or <installationdir>/jdk/jre/lib/security (Unix) on the Spotfire Server. Note: Since this file contains sensitive information it must be handled with care. The file must not be readable for unauthorized users. To list the contents of the keytab file, use the klist command-line tool which will list the principal name and security credentials. The tool is included in the bundled JDK and is only available when installed on Windows:
> <installation dir>\jdk\jre\bin\klist.exe k t K <keytab file>

To test the keytab file, use the kinit command-line tool which is also included in the bundled JDK on Windows platforms:
> <installation dir>\jdk\jre\bin\kinit.exe k t < keytab file> HTTP/<fully qualified hostname> [:<port>]@<realm>

If the keytab file is correctly set up, a ticket cache file will be created in the logged in users home directory. It can typically be found with the path C:\Users\<user>\ krb5cc_<user>. As soon as you have verified that the ticket cache was created, you must delete the ticket cache file to prevent future problems. 5 Configure Kerberos for Java: Open the file krb5.conf located in the directory <installation dir>\jdk\jre\lib\security (Windows) or <installationdir>/jdk/jre/lib/security (Unix) and edit the following values to reflect your environment:

68 (276)

TIBCO Spotfire Server 5.5

4 Configuration

MYDOMAIN: The name of the Kerberos realm, usually the same as the name of

the Windows Domain, written in upper case

mydomain: The name of the Windows Domain, written in lower case mydc: The name of the domain controller, written in lower case

Note: The arguments are case-sensitive. It is critical to use the correct case for these values! For more information, See krb5.conf on page 159. Example: Configuring Kerberos for Java in the research.example.com domain, with the two domain controllers dc01.research.example.com and dc02.research.example.com:
=============== Krb5.conf =============== [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 = dc01.research.example.com kdc = dc02.research.example.com admin_server = dc01.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

Select Kerberos as the Spotfire login method: Use the Configuration Tool or

Use the configkerberosauth command (page 195) to configure the Kerberos authentication method. The command takes the following two parameters:

Keytabfile: The fully qualified path to the spotfire.keytab file. If the keytab file is named spotfire.keytab and has been copied to the recommended directory, the default path ${java.home}/lib/security/spotfire.keytab is already correct. The shorthand ${java.home} refers to the directory <installationdir>\ jdk\jre (Windows) or the <installationdir>/jdk/jre (Unix)

TIBCO Spotfire Server 5.5

69 (276)

4 Configuration

ServicePrincipalName: Specify the same Service Principal Name that was used when creating the keytab file. Example: HTTP/ spotfireserver.research.example.com

Use the setauthmode command (page 249) to activate the Kerberos SSO authentication method. Import the configuration and restart the server for the changes to have effect.

Disable Username and Password fields in client login dialog: Since the Kerberos authentication method provides single sign-on capabilities, there is no need to prompt an end user for username and password in the Spotfire client login dialog. In fact, any entered username and password is unlikely to work, even if the credentials are fully valid. Use the Configuration Tool or the following configlogindialog command (page 200), to disable the username and password fields in the Spotfire client login dialog. Then, import the new configuration and restart the server.
> config configlogindialog allowuserprovidedcredentials=false

4.7.3 Authentication using X.509 Client Certificates

When the TIBCO Spotfire Server is set up with HTTPS and is set to require client certificates, the information from the certificates can also be used for log in purposes. This authentication method authenticates users using an X.509 Client Certificate from the Spotfire client to the Spotfire Server. A prerequisite for this authentication method is that the TIBCO Spotfire Server is set up with HTTPS and is set to require client certificates. Perform the following steps to configure Spotfire to use X.509 Client Certificates: Obtain or create, and install client certificates. Install the certificate onto clients. Configure a server to trust the client certificates. Configure the server to require client certificates. Configure the server to use client certificates to authenticate users. Steps 1 through 4 above are performed to set up the Spotfire Server with HTTPS and to require client certificates, see Configuring HTTPS on page 88 for detailed instructions. Perform the additional step 5 to set up Authentication using X.509 Client Certificates. 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 method, NTLM or Kerberos. This gives you a two-factor authentication.

1 2 3 4 5

To configure the server to use client certificates to authenticate users: Use the command configclientcertauth (page 189) to configure the Client Certificates authentication.
TIBCO Spotfire Server 5.5

70 (276)

4 Configuration

Use the setauthmode (page 249) to apply the X.509 Client Certificates SSO authentication method. Note: If you intend to use an LDAP User Directory mode, an attribute in the certificate's Distinguished Name (DN) must match an LDAP account name. By default, the server will use the Common Name (CN) attribute as account name. Use the Configuration Tool or the configclientcertauth command to configure the server to use another attribute from as account name: config config-client-cert-auth --name-attribute="DN" (will use the entire DN as account name) config config-client-cert-auth --name-attribute="subjectAltName:rfc822Name" (will use the Subject Alternative Name of type rfc822Name as account name).

4.8

Delegate Authentication Method

Spotfire clients may access the Spotfire Server through a proxy or a load balancer. In some cases, the proxy or load balancer has already forced the client to authenticate itself. Some proxies or load balancers are capable of forwarding the name of the authenticated user to the Spotfire Server. By enabling the Delegate authentication method on the Spotfire Server, it can extract the identity of the client so that the client doesn't have to authenticate twice. Any proxy or load-balancer that can propagate the username, so that it is available in the HTTP request to the server as a request attribute, is compatible. Typical scenarios are:

When both the Spotfire Server cluster and its load balancer are configured for NTLM authentication. When a load balancer is configured for X.509 Client Certificate authentication and propagates the usernames extracted from the certificates.

The Delegate authentication method may be used as a supplementary authentication method that can be used together with the main authentication method, but it can also be used as the main and only authentication method. Only use delegation when using a load balancer or proxy. If clients are always supposed to go through a load balancer to reach the TIBCO Spotfire Server, configure delegation as the main authentication method. In this case it is not possible to access a TIBCO Spotfire Server directly. Even if a load balancer is used in front of a set of TIBCO Spotfire Server instances, accessing the server directly may be desired. If this is the case, configure another authentication mechanism (any mechanism is allowed) as the main authentication method and delegation as a supplementary authentication method

TIBCO Spotfire Server 5.5

71 (276)

4 Configuration

Use the Configuration Tool or the configdelegateauth command (page 190) to set up and enable the Delegate authentication method:
EnableDelegateAuthentication (required) Requestattributename (required) Allowedhostnames (optional, but strongly recommended) Specifies whether or not the Delegate authentication method should be enabled. The name of the HTTP request attribute that contains the name of the authenticated user. The default value is REMOTE_USER. A comma-separated list of hostnames and/or IP addresses of the client computers that are permitted to log in already authenticated users by passing the usernames in the specified HTTP request attribute. If this argument is not specified, then all client computers are permitted to perform delegated authentication. As this is a potential security risk, it is strongly recommended to lock down this feature, and only give proxies or load-balancers permission to use it. A regular expression that can be used to filter the username extracted from the specified request attribute. The value of the regular expression's first capturing group will be used as the new username.

Namefilterexpression (optional)

Note: In previous releases this option was typically used for extracting the username from a composite name containing both username and domain name. Since the Spotfire Server now requires the domain name as part of the username, old configured filter expressions must be updated.
Lowercaseconversion (optional) Specifies whether or not to convert the propagated username to lower case. The default is not to convert to lower case.

4.9

Impersonation
What Is Impersonation? When the TIBCO Spotfire Servers are used in conjunction with one or more TIBCO Spotfire Web Player servers, which have been configured for certain authentication methods, for instance 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 the case when 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 password or token which can be conveyed to the TIBCO Spotfire Server cluster for login. Instead the TIBCO Spotfire Web Player server is trusted for impersonation. The

72 (276)

TIBCO Spotfire Server 5.5

4 Configuration

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 be 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. Enabling Impersonation The call from a TIBCO Spotfire Web Player server to the TIBCO Spotfire Server cluster will always require authentication. This is done as a certain user that has been specified in the configuration of the TIBCO Spotfire Web Player server. Users that should be able to impersonate must be members of the Impersonator group. It is recommended that these users do not have additional privileges. The Impersonator group can have many users, add the same user as 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 Allowed hosts fields, 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. You can also require HTTPS. All the requirements you decide to set up must be met for the impersonation call to be allowed.

TIBCO Spotfire Server 5.5

73 (276)

4 Configuration

4.10 Configuring Login Behavior

Configure how login shall work, here is a picture of the TIBCO Spotfire client login dialog.

You can configure the TIBCO Spotfire clients login dialog: If the login dialog should be displayed or not.

If users should be allowed to work offline or if they always must log in. If users can select Save my login information in the login dialog and store the login information for future automatic log in. 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. If users should be able to enter their own credentials in the login dialog or not.

Configuring RSS Feed TIBCO Spotfire Server can be configured to display messages to the end users in the login dialog, like news of upcoming scheduled maintenance. One option is to specify a path to an rss.xml file located on an TIBCO Spotfire Server, which can be updated manually. Another is to specify the URL to an external RSS feed. 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. HTML in the RSS feed is not supported. To enable all users see the news in the login dialog, set the Display behavior setting to Always. The login dialog will be shown to all users regardless of whether they have opted to save their login credentials for automatic login.

74 (276)

TIBCO Spotfire Server 5.5

4 Configuration

To configure the login behavior: Use the command configlogindialog (page 200) and restart the server. Note: Only use --show-login-dialog with the never option together with single sign-on methods: NTLM, Kerberos, and X.509 Client Certificates.

4.11 External Directories and Domains

The Spotfire Server stores information about the user accounts in the Spotfire database. It can integrate with either external directories like LDAP directories or Windows domains, where the existing environment can be integrated. Meaning that the Spotfire Server does not need to manage all information about the users and their credentials by itself. Users and groups from LDAP directories or Windows domains are called external users and groups. Starting with version 5.0, the Spotfire Server keeps track of which domain every user belongs to. A user created by an administrator directly within the Spotfire Server using the Administration Console or the Administration Manager in the TIBCO Spotfire client, belongs to the SPOTFIRE domain. The SPOTFIRE domain is also known as the internal domain and is used by the User Directory when it is running in database mode. An external user belongs to a domain with the same name as the domain it belongs to in the external directory. All TIBCO Spotfire User Interfaces that display usernames will also display the domain names as part of the usernames, except for users belonging to the internal SPOTFIRE domain. The supported external directories can have domain names in two forms: DNS domain names (for example research.example.com, a complete username will be of the form [email protected]) and

NetBIOS domain names (for example RESEARCH, a complete username will be of the form RESEARCH\someone)

When configuring the Spotfire Server, the desired domain name style must be set before the server is started for the first time. Which domain name style to select is highly dependent on the combination of authentication method and User Directory mode that is intended to set up. Note: Be careful when selecting domain name style for your system; it will affect what information the Spotfire Server will store within the Spotfire database. The domain name style can be changed using the switch domain name style command if the User Directory is in LDAP mode and is synchronizing with an Active Directory Server. For other User Directory modes, there are no tools to alter that information if the domain name style later needs to be changed. Below is a matrix showing which domain name style to use for different combinations of authentication method and User Directory mode. Combinations not supported are marked " - ". The Spotfire Server will warn and even refuse to start if you try to set up an authentication method and a User Directory with incompatible domain name styles. If you for some reason need to go ahead with an officially incompatible configuration, you will need to set the allow incompatible domain name styles configuration property to make the server start at all. One such reason could be a custom Post-Authentication
TIBCO Spotfire Server 5.5

75 (276)

4 Configuration

Filter which creates a bridge between the two originally incompatible domain name styles. (The allow incompatible domain name styles option can be set using the con figuserdir command). Collapse Domains Configuration Property Enabled
User Directory mode Database Basic Database Authentication Method Basic/LDAP/AD Basic/LDAP/other Basic/Windows NT NTLM Kerberos X.509 Client Certs LDAP/AD LDAP/other Windows NT

NetBIOS(DNS) -

NetBIOS(DNS) NetBIOS(DNS) NetBIOS(DNS) NetBIOS(DNS) NetBIOS(DNS) NetBIOS(DNS) NetBIOS(DNS)

NetBIOS(DNS) NetBIOS(DNS) NetBIOS(DNS) NetBIOS(DNS) NetBIOS(DNS) NetBIOS(DNS) NetBIOS(DNS) NetBIOS(DNS) NetBIOS(DNS) -

Unsupported combination of authentication method and User Directory mode.

Note: NetBIOS is the recommended domain name style, but DNS will also work. Collapse Domains Configuration Property Not Enabled
User Directory mode Database Basic Database Authentication Method Basic/LDAP/AD Basic/LDAP/other Basic/Windows NT NTLM Kerberos X.509 Client Certs LDAP/AD LDAP/other Windows NT

NetBIOS, DNS -

NetBIOS -

NetBIOS, DNS NetBIOS, DNS # NetBIOS, DNS # DNS -

NetBIOS, DNS NetBIOS, DNS # NetBIOS, DNS NetBIOS, DNS DNS NetBIOS, DNS NetBIOS, DNS DNS

Unsupported combination of authentication method and User Directory mode. For this combination of authentication method and User Directory mode it is recommended to enable the collapse domains option.

A consequence of the new domain tracking is that the users may have to provide the domain names as part of their usernames when logging in to the Spotfire Server. For the Basic/LDAP and Basic/Windows NT authentication methods, the setting of the wildcard domain configuration property decides how the server maps a user to a
76 (276)
TIBCO Spotfire Server 5.5

4 Configuration

domain during authentication. When the wildcard domain configuration property is enabled (it is by default), the Spotfire Server will check if the username contains a domain name, and if it does, that domain name will be used. If not, the server will attempt to authenticate the user with the provided username and password in every domain it knows about, until the combination of domain name, username and password results in a successful authentication attempt, or until there are no more domain names to try. If the wildcard domain configuration property is turned off, the domain name must be specified by the user unless it belongs to the configured default domain. This can be configured in the Configuration Tool. Note: If the wildcard domain configuration property is enabled and two identically named users in different domains have the same password, there is a risk that the wrong account is selected when one of these users log in. Thus, if security has a higher priority than user convenience, make sure to turn the wildcard domain configuration property off. There is also a risk that multiple authentication attempts will lock out the correct user. The Spotfire Server provides a configuration property that reverts to the behavior from previous releases. The configuration property is called collapse domains and enabling this means that the external domain of a user will be essentially ignored and that different users with the same username, but in different domains, will share account on the Spotfire Server. When the collapse domains configuration property is enabled, all external users and groups will be associated with the SPOTFIRE domain, regardless of which domain they belong to in the external directory. If you want to keep running the Spotfire Server without ever caring about domain names, enable both the collapse domains and wildcard domain configuration properties. Doing so will ensure that all users will belong to the internal SPOTFIRE domain and no users will have to enter a domain name when logging in. (The collapse domains configuration property can be set in the Configuration Tool or by using the configuserdir command). Note: All users will belong to one domain when the collapse domains configuration property is enabled. If there are multiple users with the same account name in different external domains, they will now effectively share the same account within the Spotfire Server. If security has a higher priority than user convenience, make sure not to enable the collapse domain configuration property. Note: It is not recommended to change the collapse domains configuration property after once having synchronized the Spotfire Server with an external directory. Doing so will lead to double accounts with different domain names for every synchronized user and group in the User Directory. The new accounts will not inherit the permissions of the old accounts.

4.12 User Directory Modes

The User Directory mode is where the User Directory retrieves information about users and groups. The supported User Directory modes are: Spotfire database Mode LDAP Mode Windows NT Mode

TIBCO Spotfire Server 5.5

77 (276)

4 Configuration

4.12.1 User Directory in Spotfire Database Mode

This User Directory mode only uses the usernames stored in the Spotfire database and does not use any external directory for user and group information. Users are added manually to the Spotfire Server via the Administration Console or through automatic registration via the Post-Authentication Filter in auto-creating mode. It is also possible to import users and groups, see commands import-groups on page 228 and import-users on page 231. This is the default User Directory mode, which does not require any additional configuration. This configuration is easy and fast to set up and is recommended for small sites.

4.12.2 User Directory in LDAP Mode

The Spotfire Server supports the following LDAP servers:

Microsoft Active Directory Oracle Directory Server, Sun Java System Directory Server, Sun ONE Directory Server, iPlanet Directory Server, Netscape Directory Server

When the User Directory is in LDAP mode, the User Directory is synchronized with one or more LDAP directories. In previous releases, the User Directory synchronized LDAP groups in the background but all user lookups in the User Directory resulted in LDAP queries. Starting with TIBCO Spotfire Server version 5.0, the User Directory will synchronize information about both users and groups in the background. All user and group lookups will now only query the Spotfire database. When upgrading to 5.0 or later, all old schedules for group synchronization will now also be used for user synchronization.

78 (276)

TIBCO Spotfire Server 5.5

4 Configuration

User Synchronization By default, the User Directory will only synchronize users (and not groups) from the LDAP directories. Once an LDAP user has been synchronized and imported to the User Directory, it will permanently be a part of the User Directory. If the LDAP user is later removed from the LDAP directory, the corresponding user in the User Directory will be disabled. Disabled accounts will still be visible within the Spotfire applications but it will not be possible for the user to log in. To prevent users from being disabled by failed synchronization attempts, for example caused by network errors, the safe synchronization option can be enabled. When this option is enabled, no users will be disabled just because they could not be found during synchronization. By default, this option is not enabled since it could be a security problem if removed LDAP users are not disabled in the User Directory. Note: It is usually not possible to log in as a removed LDAP user anyway, as the LDAP directory will block the authentication attempt if it is also responsible for authenticating users. Users may also be explicitly disabled in the LDAP directories. Such users will always be disabled in the User Directory regardless of whether or not the safe synchronization option is enabled. Group Synchronization By setting the enable group synchronization option the User Directory will also synchronize groups from the LDAP directories. This capability is useful to mirror the group hierarchies in the LDAP directories in the User Directory. When selecting the groups to be synchronized, it is possible to either list each individual group or list the context names that contains the groups. All those group context names must also be listed in the context names configuration option, otherwise they will not show up. It is possible to mix both group names and context names. If the enable group synchronization option is set and no groups or group context names are configured, the User Directory will synchronize all groups it can find in the configured context names. Synchronized LDAP groups can not be manually modified in the User Directory. Synchronized groups can be placed into manually created groups in the User Directory and thereby be granted permissions. If an LDAP group has been synchronized and it is removed from the list of groups to synchronize, it will keep the members from the last synchronization, but will revert into a normal group which is possible to modify. Note: The User Directory does not support cyclic group memberships, where the ancestor of a group is also a descendant of the same group. If the User Directory detects a group membership cycle, it will be broken up arbitrarily.

4.12.2.1 LDAP Directory Commands

The commands used to set up authentication mode and User Directory mode with an LDAP directory are listed below.

TIBCO Spotfire Server 5.5

79 (276)

4 Configuration

Commands for creating and updating an LDAP configuration:

configldapgroupsync createldapconfig updateldapconfig

Configures group synchronization for an LDAP configuration. Creates a new LDAP configuration to be used for authentication and/or the User Directory LDAP provider. Updates LDAP configurations.

Commands referencing existing LDAP configurations:

configldapuserdir listldapconfig removeldapconfig setauthmode setuserdirmode

Configures the LDAP User Directory mode. Displays LDAP configurations. Removes LDAP configurations. Sets the authentication mode Sets the User Directory mode

4.12.2.2 LDAP Authentication and User Directory Settings

The following information is required to set up LDAP authentication and User Directory mode, including LDAP group synchronization. Contact the LDAP directory administrator if you do not have the required information. The following table provides an overview of LDAP settings and their applicability. Detailed descriptions of the settings are provided below the table.

A: Applicable to LDAP as authentication mechanism UD: Applicable to LDAP User Directory mode GS: Applicable to LDAP User Directory mode with group synchronization M: Mandatory **: Required by configurations with LDAP server type Custom. These options

have template values for the non pre-defined LDAP server types. The template values can be overridden when necessary.
A AuthenticationAttribute Specifies the name of the LDAP attribute containing a user identity that can be used for authenticating with the LDAP server. A UD M LDAPServerType Specifies the type of LDAP server: ActiveDirectory, SunOne, SunJavaSystem or Custom. A UD M LDAPServerURLs A white-space separated list of LDAP server URLs.

80 (276)

TIBCO Spotfire Server 5.5

4 Configuration

A UD

ContextNames A list of distinguished names (DNs) of the containers holding the user accounts to be visible within the Spotfire Server.

A UD

Username The name of the LDAP service account to be used when searching for users and groups in the LDAP directory.

A UD

Password The password for the LDAP service account.

A UD

SecurityAuthentication Specifies the security level to use when binding to the LDAP server. The default value is simple.

A UD

** UserSearchFilter Specifies an LDAP search expression filter to be used when searching for users.

A UD

ReferralMode Specifies how LDAP referrals should be handled.

A UD

** UsernameAttribute Specifies the name of the LDAP attribute containing the user account names.

A UD

CustomLDAPProperties Multiple key-value pairs specifying additional JNDI environment properties to be used when connecting to the LDAP server.

UD

RequestControl Specifies the type of LDAP controls to be used when executing search queries to the LDAP server: Probe, PagedResultsControl, VirtualListViewControl or none.

UD

PageSize Specifies the page size to be used with the paged results control or the virtual list view control when performing search queries to the LDAP server. The page size value defaults to 1000 for both the paged results control and the virtual list view control.

UD

ImportLimit Specifies a threshold that limits the number of users that can be imported from an LDAP server to the Spotfire Server in one query.

UD

SynchronizationSchedules Specifies a list of schedules for when the synchronization task should be performed.

TIBCO Spotfire Server 5.5

81 (276)

4 Configuration

GS

GroupSynchronizationEnabled Specifies whether or not group synchronization should be enabled for this LDAP configuration.

GS

GroupNames Specifies a list of distinguished names (DNs) of either individual groups to be synchronized or a context name where all groups are to be synchronized. If the groupsynchronizationenabled option is set and the list of group names is empty, then all groups that can be found in the LDAP directory will be synchronized.

GS

** GroupSearchFilter Specifies an LDAP search expression filter to be used when searching for groups.

GS

** GroupNameAttribute Specifies the name of the LDAP attribute containing the group account names.

GS

** SupportsmemberOf Specifies whether or not the LDAP servers support a memberOf-like attribute on the user accounts that contain the names of the groups or roles that the users are members of. In general, this is true for all Microsoft Active Directory servers and all types of Sun directory servers.

GS

** MemberAttribute For all LDAP servers with support for a memberOf-like attribute, this option specifies the name of the LDAP attribute on the user account that contains the names of the groups or roles that the user is a member of.

GS

** IgnoreMemberGroups Specifies whether or not the group synchronization mechanism should recursively traverse the synchronized groups non-synchronized subgroups and include their members in the search result.

Authentication Attribute Specifies the name of the LDAP attribute containing a user identity that can be used for authenticating with the LDAP server. This attribute fills no purpose in most common LDAP configurations, but can be useful in more advanced setups, where the distinguished name (DN) does not work for authentication or where users should be able to login using a username which does not map directly to an actual LDAP account. A typical case for using this option is when setting up SASL, see Configuring SASL Authentication for LDAP on page 56. LDAP Server Type Specifies the type of LDAP server. There are four valid types: ActiveDirectory, SunOne, SunJavaSystem, and Custom.

82 (276)

TIBCO Spotfire Server 5.5

4 Configuration

When specifying one of the pre-defined server types, we will assume that default values will be applied for the most fundamental configuration options. It is possible to override the default values. When specifying a Custom LDAP server type, there is no configuration template and all fundamental configuration options must be specified explicitly. The table above shows which configuration options are required for a Cus tom LDAP server type. LDAP Server URLs A whitespace-separated list of LDAP server URLs. An LDAP server URL has the format <protocol>://<server>[:<port>]: <protocol>: Either LDAP or LDAPS

<server>: The fully qualified DNS name of the LDAP server. <port>: An optional number indicating the TCP port the LDAP service is

listening on. When using the LDAP protocol, the port number defaults to 389. When using the LDAPS protocol, the port number defaults to 636. Active Directory LDAP servers also provides a Global Catalog containing forest-wide information, instead of domain-wide information only. The Global Catalog LDAP service by default listens on port number 3268 (LDAP) or 3269 (LDAPS). The Spotfire Server does not expect any search base, scope, filter or other additional parameters after the port number in the LDAP server URLs. Such properties are specified using other configuration options for this command. Examples: LDAP server URLs
LDAP://myserver.example.com LDAPS://myserver.example.com LDAP://myserver.example.com:389 LDAPS://myserver.example.com:636 LDAP://myserver.example.com:3268 LDAPS://myserver.example.com:3269

Context Names A list of distinguished names (DNs) of the containers holding the LDAP accounts to be visible within the Spotfire Server. When specifying more than one DN, the DNs must be separated by pipe characters (|). If the specified containers contain a large number of users, but only a few should be visible in the Spotfire Server, a custom user search filter can be specified to include only the filtered users, See User Search Filter on page 84. Username The name of the LDAP service account to be used when searching for users and groups in the LDAP directory. This service account does not need to have any write permissions, but it needs to have read permissions for all configured context names (LDAP containers). For most LDAP servers, the account name is the accounts distinguished name (DN). For Active Directory, the account name can also be specified in the forms ntdomain\name or name@dnsdomain. Examples:
TIBCO Spotfire Server 5.5

83 (276)

4 Configuration

CN=spotsvc,OU=services,DC=research,DC=example,dc=COM RESEARCH\spotsvc(Note: Active Directory only) [email protected](Note: Active Directory only)

Password The password for the LDAP service account. Security Authentication Specifies the security level to use when binding to the LDAP server. The default value is simple. Only use this parameter in special cases, and use it with care in production environments.

To enable anonymous binding, it should be set to none. To enable plain username/password authentication, it should be set to simple. To enable SASL authentication, it should be set to the name of the SASL mechanism to be used. The Spotfire Server supports the two SASL mechanisms DIGESTMD5andGSSAPI. You can set multiple C flags to set the additional JNDI environment properties that the SASL authentication mechanism typically requires.

A typical case for using this option is when setting up SASL, see Configuring SASL Authentication for LDAP on page 56 User Search Filter This parameter specifies an LDAP search expression filter to be used when searching for users. If only a subset of all the users in the specified LDAP containers should be allowed access to the Spotfire Server, a restrictive user search filter can be specified. For instance, the search expression can be configured so that it puts restrictions on which groups the users belong to, or which roles they have.

For Active Directory servers, the parameter value defaults to objectClass=user. For Active Directory servers, access can be restricted to only those users belonging to a certain group by using a search expression with the pattern &(objectClass=user)(memberOf=<groupDN>) where <groupDN> is to be replaced by the real DN of the group to which the users must belong. If the users are divided among multiple groups, use the pattern &(objectClass=user)(|(memberOf= <firstDN>)(memberOf=<secondDN>)). Add extra (memberOf=<groupDN>) sub-expressions as needed. Example: &(objectClass=person)(isMemberOf=cn=projectx,dc=example,dc=com)

For any version of the Sun Directory Servers, it defaults to objectClass=person. For a Sun Java System Directory Server version 6 and later, the same effect can be achieved by using a search expression with the pattern &(objectClass= person)(isMemberOf=<groupDN>). If the users are divided among multiple groups, use the pattern &(objectClass=person)(|(isMemberOf=

84 (276)

TIBCO Spotfire Server 5.5

4 Configuration

<firstDN>)(isMemberOf=<secondDN>)). Add extra (isMemberOf=<groupDN>)

sub-expressions as needed. Example: &(objectClass=person)(isMemberOf=cn=projectx,dc=example,dc=com)

For Sun ONE Directory Servers as well as the newer Sun Java System Directory Servers or the older iPlanet/Netscape Directory Servers, access can be restricted to only those users having certain specific roles. The search expression for role filtering must match the pattern &(objectClass=person)(nsRole=<roleDN>). If multiple roles are of interest, use the pattern &(objectClass=person)(|(nsRole= <firstDN>)(nsRole=<secondDN>). Add extra (nsRole=<roleDN>) sub-expressions as needed. Example: &(objectClass=person)(isMemberOf=cn=projectx,dc=example,dc=com)

The syntax of LDAP search expression filters is specified by RFC 4515. Please consult this specification for information about more advanced filters. Referral Mode This argument specifies how LDAP referrals should be handled. Valid arguments are follow (automatically follow any referrals), ignore (ignore referrals) and throw (fail with an error). The default and recommended value is follow. Username Attribute Specifies the name of the LDAP attribute containing the user account names. For Active Directory servers the value defaults to sAMAccountName. For a Sun Java System Directory Server or any older Sun ONE Directory Server or iPlanet/Netscape Directory Server with a default configuration, it defaults to uid. Custom LDAP Properties Multiple key-value pairs specifying additional JNDI environment properties to be used when connecting to the LDAP server. For instance, specifying the key java.naming.security.authentication and the value simple have the same result as setting the SecurityAuthentication option to simple. Request Control This option determines the type of LDAP controls to be used when executing search queries to the LDAP server. Valid controls are Probe, PagedResultsControl, VirtualListViewControl and none. The default behavior is to probe the LDAP server for the best supported request control. The paged results control is always preferred, since it provides the most efficient way of retrieving the result of the query. The virtual list view control can also be used to retrieve a large number of users, if the paged results control is not supported. The virtual list view control will automatically be used together with a sort control. Both the paged results control and the virtual list view control support a configurable page size, as specified by the pagesize option. Page Size This argument specifies the page size to be used with the paged results control or the virtual list view control when performing search queries to the LDAP server. The page
TIBCO Spotfire Server 5.5

85 (276)

4 Configuration

size value defaults to 1000 for both the paged results control and the virtual list view control. Import Limit This argument specifies a threshold that limits the number of users that can be imported from an LDAP server to the Spotfire Server in one query. This can be used to prevent accidental flooding of the Spotfire Servers User Directory when integrating with an LDAP server with tens or even hundreds of thousands of users. By setting an import limit, the administrator can be sure that an unexpected high number of users wont affect the servers performance. By default, there is no import limit. To explicitly request unlimited import, set the parameter value to 1. All positive numbers are treated as an import limit. Leave this parameter untouched. in most cases. Group Synchronization Enabled Specifies whether or not group synchronization should be enabled for this LDAP configuration. Group Names Specifies a list of distinguished names (DNs) of either individual groups to be synchronized or a context name where all groups are to be synchronized. If specifying a context name here, the same context name must also be explicitly listed in context names. If the group synchronization enabled option is set and the list of group names is empty, then all groups that can be found in the LDAP directory will be synchronized. Synchronization Schedules Specifies a list of schedules for when the group synchronization task should be performed. The schedules are specified in the cron format, where each schedule consists of either five fields or one shorthand label. The five fields are, from left to right, with their valid ranges:

minute(059) hour(023) dayofmonth(131) month(112) dayofweek(07,whereboth0and7indicateSunday)

A field may also be configured with the wildcard character (*), indicating that any moment in time matches this field. A group synchronization is triggered when all fields match the current time. If both day of month and day of week have non-wildcard values, then only one of them has to match. There are also the following shorthand labels that can be used instead of the full cron expressions:
@yearly or @annually:runonceayear(equivalentto0 0 1 1 *) @monthly:runonceamonth(equivalentto0 0 1 * *) @weekly:runonceaweek(equivalentto0 0 * * 0)
86 (276)
TIBCO Spotfire Server 5.5

4 Configuration

@daily or @midnight:runonceaday(equivalentto0 0 * * *) @hourly:runonceanhour(equivalentto0 * * * *) @minutely:runonceaminute(equivalentto* * * **) @rebootor@restart:runeverytimetheSpotfireServerisstarted

Refer to the Wikipedia overview article on the cron scheduler. Group Search Filter This parameter specifies an LDAP search expression filter to be used when searching for groups.

For Active Directory servers, the parameter value defaults to objectClass=group For Sun Java System Directory Servers, it defaults to objectClass=
groupOfUniqueNames

For Sun ONE Directory Servers, it defaults to &(|(objectclass=

nsManagedRoleDefinition)(objectClass=nsNestedRoleDefinition))(objectclass= ldapSubEntry)

Group Name Attribute Specifies the name of the LDAP attribute containing the group account names:

For Active Directory servers the value defaults to sAMAccountName For any version of the Sun directory servers with a default configuration, it defaults to cn

Supports memberOf Specifies whether or not the LDAP servers support a memberOf-like attribute on the user accounts that contain the names of the groups or roles that the users are members of. In general, this is true for all Microsoft Active Directory servers and all types of Sun directory servers. Member Attribute For all LDAP servers with support for a memberOf-like attribute, this option specifies the name of the LDAP attribute on the user account that contains the names of the groups or roles that the user is a member of. In general, this includes all Microsoft Active Directory server and all types of Sun Directory Servers.

For Microsoft Active Directory servers, the parameter value defaults to

memberOf

For Sun ONE Directory Servers, it defaults to nsRole For Sun Java System Directory Server version 6.0 or later, it defaults to isMemberOf. To use the roles with the Sun Java System Directory Server, override the default value by setting this argument to nsRole.

For some LDAP servers with configurations of type Custom, there is no memberOf-like attribute, this is declared by setting the supports memberOf option to false. In those cases, this argument specifies the LDAP attribute on the group account that contains the names of its members.
TIBCO Spotfire Server 5.5

87 (276)

4 Configuration

Note: All configurations with the memberOf option set to false will use a far less efficient group synchronization algorithm that will generate more traffic to the LDAP servers, because the Spotfire Server will first have to search for the distinguished names (DNs) of the group members within the groups, and then perform repeated lookups to translate the member DN to the correct account name. Ignore Member Groups This argument determines whether or not the group synchronization mechanism should recursively traverse the synchronized groups non-synchronized subgroups and include their members in the search result. For Microsoft Active Directory servers, the parameter value defaults to false so that all inherited group memberships are correctly reflected. For any version of the Sun Directory Servers, it defaults to true, since the role and groups mechanisms in those servers automatically include those members.

4.12.3 User Directory in Windows NT Mode

Kept for legacy support. Use the Configuration Tool or the command config-windows-userdir on page 207 to configure a User Directory in Windows NT Mode.

4.13 Configuring HTTPS

By default, Spotfire uses the HTTP protocol for communication between clients and the server. To achieve a higher level of security, it is recommended to use the HTTPS protocol instead, ensuring encryption between clients and the server. In order to set up HTTPS, you must first have the following:

a public Certificate Authority (CA) certificate a server certificate and private key issued by the CA

The server private key can be either in the PKCS#12 or JKS format. You can obtain these objects from a commercial Certificate Authority or create them using CA software. Please refer to the documentation of your Certificate Authority on how to obtain or create them. In this manual, there are also reference instructions on how to create a self-signed certificate in the section Creating a Self-Signed Server Certificate on page 150 Procedure 1 2 3 4 5 6
88 (276)

Stop the Spotfire Server (if it is running). Set the password for the Java trusted keystore. Import the CA Certificate. Install the servers certificate. Install the servers private key Configure the Spotfire Server to use the HTTPS protocol.
TIBCO Spotfire Server 5.5

4 Configuration

Now, the Spotfire Server communicates using HTTPS. 7 8 9 Obtain or create, and install client certificates. Install the certificate onto clients. Configure a server to trust the client certificates. Now, certificates can be used both ways for client and server communication. Configure the server to require client certificates. Now, certificates are required for all communication between clients and server. To stop the Spotfire Server: See Start and Stop the Spotfire Server on page 102.

10

To set the password for the Java trusted keystore: The default password for the JVM CA certificate database is changeit. Change it using the keytool command, located in the <installationdir>/jdk/jre/bin folder installed with the Spotfire Server. The trusted keys are stored in the file cacerts located in the folder <installation dir>/jdk/jre/lib/security. Set a new password by executing the following command from a command prompt or terminal:
> <installation dir>/jdk/jre/bin/keytool storepasswd keystore <installation dir>/jdk/ jre/lib/security/cacerts

Example: Windows
C:\>c:\tibco\tss\5.5.0\jdk\jre\bin\keytool storepasswd keystore c:\tibco\tss\5.5.0\ jdk\jre\lib\security\cacerts

To import the CA certificate: To import a CA certificate into the JVM CA certificate database (cacerts file), execute the following command:
> <installation dir>/jdk/jre/bin/keytool importcert v keystore <installation dir>/jdk/ jre/lib/security/cacerts alias <aliasname> file <certfile>

The <aliasname> must be a unique identifier that clearly identifies the CA certificate. The <certfile> is the file containing the CA certificate to import. Windows example where you will be prompted for the password set above:
C:\>c:\tibco\tss\5.5.0\jdk\jre\bin\keytool importcert v keystore c:\tibco\tss\5.5.0\ jdk\jre\lib\security\cacerts alias exampleCA file C:\TMP\exampleca.cer

Note: If the CA certificate is stored in BASE 64 encoded DER format, make sure that the file starts with BEGINCERTIFICATE. Otherwise, the import will fail. You will be prompted for the current password (changeit) and twice for a new password. After changing the password, review the access permissions for the cacerts file to make sure that no one is allowed to modify it.
TIBCO Spotfire Server 5.5

89 (276)

4 Configuration

To verify a certain CA certificate in the JVM CA certificate database:

> <installation dir>\jdk\jre\bin\keytool list v keystore c:\tibco\tss\5.5.0\jdk\jre\lib\ security\cacerts alias exampleCA

Windows example listing a preinstalled VeriSign CA certificate:

C:\>C:\tibco\tss\5.5.0\jdk\jre\bin\keytool list v keystore c:\tibco\tss\5.5.0\jdk\jre\ lib\security\cacerts alias verisignclass1g2ca Enter keystore password: Alias name: verisignclass1g2ca Creation date: Mar 25, 2004 Entry type: trustedCertEntry Owner: OU=VeriSign Trust Network, OU="(c) 1998 VeriSign, Inc. For authorized u se only", OU=Class 1 Public Primary Certification Authority G2, O="VeriSign, I nc.", C=US Issuer: OU=VeriSign Trust Network, OU="(c) 1998 VeriSign, Inc. For authorized use only", OU=Class 1 Public Primary Certification Authority G2, O="VeriSign, Inc.", C=US Serial number: 4cc7eaaa983e71d39310f83d3a899192 Valid from: Mon May 18 02:00:00 CEST 1998 until: Wed Aug 02 01:59:59 CEST 2028 Certificate fingerprints: MD5: DB:23:3D:F9:69:FA:4B:B9:95:80:44:73:5E:7D:41:83 SHA1: 27:3E:E1:24:57:FD:C4:F9:0C:55:E8:2B:56:16:7F:62:F5:32:E5:47 Signature algorithm name: SHA1withRSA Version: 1

To install the Server certificate and private key: The server certificate and its corresponding private key must be stored in either the PKCS#12 or the Java Keystore (JKS) format. Install the server certificate and private key in the following directory:
<installation dir>/jdk/jre/lib/security/[ServerHostname].p12

To configure the Spotfire Server to use the HTTPS protocol: To set the server to communicate using the HTTPS protocol, edit the configuration file <installationdir>/tomcat/conf/server.xml. In the Spotfire service section locate the section that defines the Connector:
<!-<Connector port="443" maxHttpHeaderSize="16384" connectionTimeout="30000" enableLookups="false" URIEncoding="UTF-8" disableUploadTimeout="true" server="TIBCO Spotfire Server" SSLEnabled="true" scheme="https" secure="true"

90 (276)

TIBCO Spotfire Server 5.5

4 Configuration

keystoreFile="../jdk/jre/lib/security/[ServerHostname].p12" keystorePass="changeit" keystoreType="pkcs12" clientAuth="false"/> -->

Remove the comment markers <! and > . Then, to disable unencrypted traffic (HTTP), add comment markers around the existing HTTP connector. Be sure to replace [ServerHostname] with the actual hostname of the Spotfire Server, and changeit with the password to the keystore. Note: The Apache Tomcat stores the password in clear text. You should secure the file and/or the server to prevent users from accessing it. For a detailed view of the file server.xml, see the section server.xml on page 157. Now, the Spotfire Server communicates using HTTPS.

To obtain and install client certificates

To issue CA-certificates, contact your certificate authority for information. To buy CA-certificates, contact your certificate authority for information. To Self-Sign certificates, reference instructions on how to create a self-signed certificate are given in section Creating and Installing a Self-Signed Client Certificate on page 152.

Internet Explorer is usually used to install a certificate on the client by connecting to the web page of the certificate authority: Contact your certificate authority for more information.

To configure a server to trust the client certificates: For the servers to trust the client certificates, they 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 Server can read. Once you have the CA certificate in a file on the Spotfire Server, issue the following command to create a truststore and import the CA certificate to them:
<installation dir>/jdk/bin/keytool.exe importcert v file <cert_file.cer> keystore castore.jks C:\>c:\tibco\tss\5.5.0\jdk\jre\bin\keytool importcert v keystore c:\tibco\tss\5.5.0\ jdk\jre\lib\security\cacerts alias exampleCA file C:\TMP\exampleca.cer

Place the truststore file castore.jks in <installation dir>/jdk/jre/lib/security. Edit the server.xml by adding the path to the truststore file, its password and its type, see page 90 and the next step for instructions. Now, certificates can be used both ways for client and server communication.

TIBCO Spotfire Server 5.5

91 (276)

4 Configuration

To 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 <installationdir>/tomcat/conf. In the Spotfire Service definition, under the HTTPS Connector definition, locate this assignment, clientAuth="false", and set it to true. Now, certificates are required for all communication between clients and server.

To start the Spotfire Server: When you have configured HTTPS you can start the Spotfire Server, for example by starting the Windows Service or running the startup script. See Start and Stop the Spotfire Server on page 102.

To use encryption in a load-balanced environment: In a load-balanced environment, clients communicate using HTTP or HTTPS with the load balancer, which 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 on page 172 in the Appendix.

4.14 Configuring LDAPS

In an LDAP environment, where the Spotfire system communicates 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 server to communicate using SSL. Then you must get the Spotfire Server(s) to trust this certificate if you are using a self-signed certificate. This is done by following steps: Export the certificate to file and copy it to the Spotfire Server. With a command prompt or shell, navigate to the directory <installation dir>/jdk/jre/ lib/security and execute the keytool command located in the <installation dir>/jdk/bin/ directory to import the certificate:
../../bin/keytool import file ldapserver.crt keystore cacerts alias spotfire_ldaps

1 2

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:
../../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. Use the createldapconfig (page 210) or the updateldapconfig (page 261) command to activate LDAPS.
92 (276)
TIBCO Spotfire Server 5.5

4 Configuration

4.15 Using Kerberos to log in to the Spotfire Database

To increase security in the Spotfire system, you may want to set up the Spotfire Server to authenticate with the Spotfire database using the Kerberos protocol. This only affects how the database connections are authenticated and has nothing to do with clients to the Spotfire Server using the Kerberos authentication method. These instructions assume that the person following them has experience with the database and possibly also with setting up Kerberos in other setups. Prerequisites

Windows Domain Controllers running Windows Server 2003 SP1 or later. A computer with the MicrosoftActiveDirectoryUsersandComputersMMC snap-in. A computer with the MicrosoftSupportTools installed. A domain administrator account or a user account which is a member of the built in AccountOperators domain group, or any account with equivalent permissions. The database server must already be installed and configured for both Kerberos authentication and username/password authentication. Microsoft Active Directory is used as Kerberos environment. If the database is an Oracle database, then download Oracles latest JDBC driver (ojdbc6.jar) from Oracles web page. If the database is a Microsoft SQL Server database, use the bundled Microsoft JDBC driver (sqljdbc4.jar). Version 4.0 of the sqljdc4.jar driver introduced the new authenticationScheme= JavaKerberos directive, which is required.

TIBCO Spotfire Server 5.5

93 (276)

4 Configuration

4.15.1 Workflow Overview

The following steps are required to configure Authentication of the Spotfire Database using Kerberos. Each step is later explained in detail. 1 2 3 4 5 6 7 8 9 10 Create a Windows domain account for the Spotfire database Microsoft SQL Server: Create the Spotfire database Oracle: Create and configure the Spotfire database account to the Windows domain account Install the Spotfire Server Install the database vendor's JDBC driver Configure Kerberos for Java Optional: Create a Kerberos keytab file for the Spotfire database account Create a JAAS application configuration for the Spotfire database connection pool Register the JAAS application configuration file with Java. Connect to the Spotfire database by running the bootstrap command or by using the Configuration Tool.

4.15.2 Detailed Instructions

Create a Windows domain account for the Spotfire database: You must be logged in as a domain administrator, a user who is a member of the built in AccountOperators domain group, or a user with equivalent privileges. Launch the Active Directory Users and Computers MMC snap-in and create a normal user account with the following properties:

Use the same identifier in the Fullname, Userlogonname and Userlogonname (preWindows2000) fields and make sure to use only lower case characters and that there are no spaces in these fields. Check the Passwordneverexpires option. Clear the Usermustchangepasswordatnextlogon option. Recommended: Check the Accountissensitiveandcannotbedelegated option.

Microsoft SQL Server: Create the Spotfire database: Edit and run the create_databases_ia.bat script. This will create a SQL Server database account and connect it to the previously created Windows domain account. See Prepare the Database on page 17.

Oracle: To create and configure the Spotfire database account to the Windows domain account: Edit and run the create_databases.batscript. This will create a normal Oracle database account that authenticates with username and password. See Prepare the Database on page 17.

94 (276)

TIBCO Spotfire Server 5.5

4 Configuration

Log in to the Oracle database instance with SYSDBA privileges to manage accounts. Example: Connecting to a database with connection identifier ORCL as sysdba
> sqlplus sys@ORCL as sysdba

Alter the Spotfire database account so that it is identified externally by running the following command:
SQL> alter user <SERVERDB_USER> identified externally as '<SERVERDB_USER>@ <REALM>';

Replace <SERVERDB_USER> and <REALM> with the Spotfire database account name and the Kerberos realm. Make sure to use upper case when specifying the Kerberos realm Example:
SQL>alteruserspotuseridentifiedexternallyas'[email protected]';

Test the Kerberos-enabled Spotfire database account by launching a command prompt running as the created Windows domain account. It should now be possible to connect to the database using the following command, assuming the connection identifier is ORCL:
> sqlplus /@ORCL

Note: It is assumed that Kerberos authentication is already set up for the Oracle client.

To install the Spotfire Server: Install the Spotfire Server following the instructions in the section Install Spotfire Server on page 23.

To install a vendor database driver: Install a vendor database driver as described in the section Install Database Drivers on page 27.

To configure Kerberos for Java: Follow the instructions in Configure Kerberos for Java: on page 68. Optional: To create a keytab file for the Kerberos service account: Option 1: Using the ktpass.exe command included with the MicrosoftSupportTools On a computer with the MicrosoftSupportTools installed (there is no need to be logged in as a privileged user), execute the following command:
> ktpass /princ <database account name>@<REALM> /ptype krb5_nt_principal / crypto rc4hmacnt /out spotfiredatabase.keytab kvno0/pass *

Replace the <databaseaccountname> and <REALM> with the appropriate values. Note: All values are case sensitive.

TIBCO Spotfire Server 5.5

95 (276)

4 Configuration

serviceaccountname: The userloginname of the Spotfire database account (written in lower case) REALM: The name of the Kerberos realm, which is the DNS domain name written in upper case The tool will prompt for the password of the service account. Enter the same password as when creating the Spotfire database account. It is not critical to use the name spotfiredatabase.keytab for the keytab file, but the following instructions assumes that this name will be used. Note: If you ever change the password of the Kerberos service account in the future, you must re-create the keytab file again. Example: Creating a keytab file for the spotuser Spotfire database account in the research.example.com domain:

> ktpass /princ [email protected] /ptype krb5_nt_principal / crypto rc4hmacnt /out spotfiredatabase.keytab kvno0/pass *

Finally, copy the spotfiredatabase.keytab file to the directory <installationdir>\jdk\jre\ lib\security (Windows) or <installation dir>/jdk/jre/lib/security (Unix) on the Spotfire Server. Note: Since this file contains sensitive information it must be handled with care. The file must not under any circumstances be readable for unauthorized users. Option 2: Using the ktab.exe command included with the bundled JDK On the computer where the Spotfire Server is installed, execute the following command:
> ktab k spotfiredatabase.keytab a <database account name>

Replace the <databaseaccountname> as described in Option 1 above. It is not critical to use the name spotfiredatabase.keytab for the keytab file, but the following instructions assumes that this name will be used. The tool will prompt for the password of the service account. Enter the same password as when creating the Spotfire database account. Note: If you ever change the password of the Kerberos service account in the future, you must re-create the keytab file again. Verify the created keytab by running the klist and kinit utilities:
> klist k <installation dir> spotfiredatabase.keytab > kinit k t spotfiredatabase.keytab <database account name>@<realm>

Example: Creating and verifying a keytab file for the serverdb_user Spotfire database account in the research.example.com domain:
> ktab k spotfiredatabase.keytab a serverdb_user > klist k spotfiredatabase.keytab > kinit k t spotfiredatabase.keytab [email protected]

96 (276)

TIBCO Spotfire Server 5.5

4 Configuration

Finally, copy the spotfiredatabase.keytab file to the directory <installationdir>\jdk\jre\ lib\security (Windows) or <installation dir>/jdk/jre/lib/security (Unix) on the Spotfire Server. Note: Since this file contains sensitive information it must be handled with care. The file must under any circumstances not be readable for unauthorized users.

To create a JAAS application configuration for the Spotfire database connection pool: Create the file <installationdir>\jdk\jre\lib\security\spotfiredatabase.login (Windows) or <installationdir>/jdk/jre/lib/security/spotfiredatabase.login (Unix) and populate it with one of the options shown below.

To acquire a Kerberos ticket using a keytab file, select alternative 1 To acquire a Kerberos ticket using a username and a password, select alternative 2. To acquire a Kerberos ticket using the identity of the account running the Spotfire Server process, select alternative 3.

Note: Regardless if you select alternative 1, 2 or 3 below, save the file as spotfire_database.login. 1 To acquire a Kerberos ticket using a keytab file: Replace <service account name> and <realm> with the name of the Spotfire database account and the Kerberos realm. Make sure to use lowercase letters for the account name and uppercase for the realm name.
DatabaseKerberos { com.sun.security.auth.module.Krb5LoginModule required debug=true storeKey=true useKeyTab=true keyTab="${java.home}/lib/security/spotfire-database.keytab" principal="<SERVERDB_USER>@<REALM>"; };

To acquire a Kerberos ticket using a username and a password: Replace <serviceaccountname> and <password> with the name and the password of the Spotfire database account.
DatabaseKerberos { com.sun.security.auth.module.Krb5LoginModule required debug=true storeKey=true useKeyTab=false doNotPrompt=false; };

TIBCO Spotfire Server 5.5

97 (276)

4 Configuration

To acquire a Kerberos ticket using the identity of the account running the Spotfire Server process: To make it possible to login to the Spotfire database as the user currently running the server, the connection pool must be able to acquire the initial Ticket-Granting-Ticket (TGT) from the Spotfire Servers hosts native Ticket Cache. On modern Windows operating systems, the TGT session key cannot be exported unless the following registry key is modified:
[HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\Lsa\Kerberos\ Parameters]"allowtgtsessionkey"=dword:00000001 DatabaseKerberos { com.sun.security.auth.module.Krb5LoginModule required debug=true storeKey=true useTicketCache=true doNotPrompt=false; };

To register the JAAS application configuration file with Java: The spotfire_database.login file that was created above must be registered in Java. Open the file <installationdir>/jdk/jre/lib/security/java.security in a text editor and add the following lines at the end of the file:
# Register Java Authentication & Authorization Services (JAAS) configurations login.config.url.1=file:${java.home}/lib/security/ spotfire-database.login

Configure the database connection for the TIBCO Spotfire Server: Execute the bootstrap command (page 179). If the bootstrap command below executes successfully, the database connection is correctly established after using Kerberos authentication. To bootstrap the Spotfire Server, execute the bootstrap command:
> config bootstrap test driverclass=oracle.jdbc.OracleDriver databaseurl= <database url> kerberoslogincontext=DatabaseKerberos Coracle.net.authentication_services=(KERBEROS5)

Replace <databaseurl>with the JDBC connection URL. When using a username and a password to request the Kerberos ticket, make sure to also specify the username and password arguments. Oracle example: A JDBC URL
jdbc:oracle:thin:@research.example.com:1521:orcl
98 (276)
TIBCO Spotfire Server 5.5

4 Configuration

> config bootstrap test driverclass=com.microsoft.sqlserver.jdbc.SQLServerDriver databaseurl=<database url> kerberoslogincontext=DatabaseKerberos

Microsoft SQL Server example: A JDBC URL Replace <databaseurl> with the JDBC connection URL. This URL must include ;inte gratedSecurity=true;authenticationScheme=JavaKerberos options.
jdbc:sqlserver://db.research.example.com:1433;DatabaseName= spotfire_server;integratedSecurity=true;authenticationScheme=JavaKerberos

Note: It makes no sense to configure a specific Configuration Tool password when using a connection pool that logs in to Kerberos using a keytab file or retrieving the Ticket-Granting Ticket (TGT) from the native ticket cache. However, it does have a function in the scenario with a connection pool that logs in to Kerberos using a username and password.

4.16 Exporting and Importing Configuration Files

Configurations are stored as xml-files in the database. The configuration.xml file can be viewed, edited and sent to support for inspection. To do this, export the file from the database. When you import the configuration.xml file to the database, it is imported and also set as the active configuration. The configuration settings can be exported to file for backup purposes, or to be imported into another cluster to set up several clusters with similar settings. Some configuration properties in the Spotfire system are rarely used and can not be set using commands. To use such configuration properties, export the configuration to an XML file, edit it and import it back into the Spotfire database. This procedure can also be used to configure features that require complex commands, for example several authentication options.

4.17 Configuring a Specific Directory for Library Import and Export

For performance and security reasons, Library Import and Export Operations can only be performed from a specific directory on the TIBCO Spotfire Server. If this for some reason is inconvenient, it can be altered. Files that are to be imported into the Spotfire Library by Spotfire Administrators need to be placed in a specific directory in order to be imported. By default this is: <serverinstallationdirectory>/tomcat/applicationdata/library. For most intents and purposes, this setting does not need to be changed. Use the command config-import-export-directory on page 193 in the Library group.

TIBCO Spotfire Server 5.5

99 (276)

4 Configuration

4.18 Attachment Manager

The Attachment Manager is used when large amounts of data are transferred between TIBCO Spotfire Clients, TIBCO Spotfire Web Players or web browsers and the TIBCO Spotfire Server. The Library uses the Attachment Manager to transfer the actual content when downloading or saving items, and Information Services uses it for downloading the result of an information link execution. The Attachment Manager can cache Library Items and Information Links. This Caching is enabled by default, but can be completely disabled using the library.contentcach ingenabled and informationservices.resultcaching settings. For Library Items, the cache will never return any stale data and they are cached by default. For Information Links, each link has to be explicitly set as "cacheable" when it is created. It is the responsibility of the user that creates the information link not to mark it as cacheable if the result may depend on things outside the control of Information Services, such as database row level security. The cache is encrypted by default and the size is limited in terms of disk usage. If items are to be evicted, a least recently used-algorithm is used. Library Items have higher priority and will always be evicted after Information Links. Attachments in the cache will time out and be removed after a configurable amount of time. Default values for the cache expiration time and the max cache size are 24 hours (68400 seconds) and 10 GB (10240 MB).

100 (276)

TIBCO Spotfire Server 5.5

5 Administration

Administration
Before installing TIBCO Spotfire clients on end user machines, administrative tasks such as setting up software updates, setting up users groups, deploying a Spotfire distribution and packages, and management of licenses and setting of preferences, have to be performed. There are a number of tools for administrative tasks:

Administration Console: http[s]://<server>:<serverport>/spotfire A web application for users, groups and deployments management. The manual is available in the TIBCO Spotfire Deployment distribution. Server Logs and Diagnostics: http[s]://<server>:<serverport>/spotfire See Server Logs and Diagnostics on page 155. Administration Manager: TIBCO Spotfire - Tools > Administration Manager A tool in TIBCO Spotfire for licenses and preferences management. Library Administration: TIBCO Spotfire - Tools > Library Administration A tool in TIBCO Spotfire Library management, including import and export.

Note: Javascript must be enabled in your web browser for the Administration Console to launch.

5.1
1

The First Administration Process

Start the TIBCO Spotfire Server service The server must be started to be able to access the Administration Console. See Start and Stop the Spotfire Server on page 102. Define Users and Groups See Manage Users and Groups on page 104. Deploy client packages to the Spotfire Server A Spotfire distribution and usually additional packages are required not only for users to be able to run Spotfire, but also for the following administration steps. See Prepare TIBCO Spotfire for Software Updates (Deploy TIBCO Spotfire) on page 105. Install TIBCO Spotfire for the Spotfire Administrators usage See Install TIBCO Spotfire for Spotfire Administrator Usage on page 105. Assign Licenses and define Preferences See Manage Licenses and Preferences on page 105. Install Spotfire clients on End Users Machines See Install TIBCO Spotfire Clients on End Users Machines on page 106. Recommended: Enable use of the Data Functions See Enable Data Functions Usage on page 106. In order to use these Data Functions, TIBCO Spotfire Statistics Services needs to be installed and configured as well. The Data Functions provide Spotfire users immediately useful analytic functionality, as well as detailed and flexible templates to help users develop their own Data Functions more quickly and easily. Installing these Data Functions will make these features potentially available to your users.

2 3

4 5 6 7

TIBCO Spotfire Server 5.5

101 (276)

5 Administration

Optional: Enable use of the Demo Database See Enable Demo Database Usage on page 107.

5.2

Start and Stop the Spotfire Server

5.2.1 Windows
On a Windows machine the procedure differs depending on if the Windows service is created or not, and if the Spotfire Server is run as a Windows Domain user. When started, this application writes log files to the <installationdir>/tomcat/logs directory. The procedure for stopping the server is also described. Troubleshooting To verify that the server can be started, launch a command prompt, go to <installation dir>/tomcat/bin and run the command catalina.bat run or catalina.sh run. Server debug info will be written to the console. Launch a browser and go to the Spotfire server start page: http://<hostname>/spotfire:<port>. Select Open Logs and Diagnostics to verify that authentication works and you are an administrator user. Note that memory settings are different from when running as a Windows service.

5.2.1.1 Windows, Service Exists

Select Start > Control Panel > Administrative Tools > Services. Locate the service called TIBCO Spotfire Server 5.5 and start or stop it. The Spotfire Server Windows service can also be started/stopped from a command prompt (you need to be logged in as an Administrator):

netstartTss550 netstopTss550

Note: If you need to reinstall the Windows Service after installation, run the bat file <installation dir>/tomcat/bin/service.bat with the argument install: <installation dir>/ tomcat/bin/service.batinstall. You can also run this script with the argument remove to remove the Windows Service: <installationdir>/tomcat/bin/service.bat remove

5.2.1.2 Windows, No Service

If you did not install a Windows service you must start the Spotfire Server manually. 1 2 3 4 Log in to the Spotfire Server machine as an administrator. Start a command prompt. Navigate to the folder <installationdir>/tomcat/bin Run the startuptomcat.bat file.

102 (276)

TIBCO Spotfire Server 5.5

5 Administration

Response: The Spotfire Server starts. The server will stop running if you close the command prompt or log out of the machine.

5.2.1.3 Windows, Service Exists, Integrated Authentication for SQL Server

If your database server uses Windows Integrated Authentication, your Spotfire Server must run as a Windows Domain user that has permissions to use the Spotfire database. 1 2 3 Select Start > Control Panel > Administrative Tools > Services. Locate the service called TIBCO Spotfire Server 5.5. Double-click it to open its Properties dialog. Select the Log On tab. Select the This account radio button and enter the user credentials of the Domain User set up with the database preparation script create_databases_ia.bat. Click OK. Start or stop the service.

5.2.1.4 Windows, No Service, Integrated Authentication for SQL Server

If your database server uses Windows Integrated Authentication, your Spotfire Server must run as a Windows Domain user that has permissions to use the Spotfire database. 1 2 3 4 Log in to the Spotfire Server machine as the Domain User set up with the database preparation script create_databases_ia.bat. Start a command prompt. Go to the folder <installationdir>/tomcat/bin Run the startuptomcat.bat file Response: The Spotfire Server starts. The server will stop running if you close the command prompt or log out of the machine.

5.2.2 Linux
For Red Hat and SUSE systems the service starts on system startup. Note: Only a user with root user privileges can start and stop the server.

1 2

Manual Spotfire Server Start: Log in as root or run with sudo -s. Run the command /etc/init.d/tssstart.

TIBCO Spotfire Server 5.5

103 (276)

5 Administration

1 2

Manual Spotfire Server Stop: Log in as root or run with sudo -s. Run the command /etc/init.d/tssstop.

5.2.3 Solaris

To start Spotfire Server on reboot: To configure Spotfire Server to start automatically when the Solaris machine is rebooted run the install_startup_script.sh script: 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. Navigate to the <installationdir>/tomcat. Execute the file install_startup_script.sh. Response: The Spotfire Server will start automatically after each machine reboot. To start or stop the server right now, run either the script /etc/init.d/tssstartor/etc/init.d/
tssstop

2 3

Note: The install_startup_script.sh script copies the script tss, also located in <installation dir>/tomcat, to the /etc/init.d directory and places symbolic links to this scripts in the appropriate runlevel directories (for example /etc/rc2.d).

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 <installationdir>/tomcat/bin with the same user as the one who installed the Spotfire Server. Response: The Spotfire Server starts.

5.3

Manage Users and Groups

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, groups and deployments can be created, deleted and managed in the Administration Console. You can for example set new passwords, administer group membership of users, assign primary groups and assign a deployment area to groups. See the Spotfire Administration Console online help for more information.

104 (276)

TIBCO Spotfire Server 5.5

5 Administration

http[s]://<server>:<serverport>/spotfire

5.3.1 Prepare TIBCO Spotfire for Software Updates (Deploy TIBCO Spotfire)
When Spotfire users log in to the Spotfire Server from a Spotfire client, the version of the client software is compared to the software on the server (the packages deployed to the server). A deployment must exist on the server for the user to be able to use Spotfire. The deployment is a bundle of software packages and licenses that is uploaded to the Spotfire database. A Spotfire deployment is created by uploading a TIBCO Spotfire Deployment distribution, and possibly additional packages to the Spotfire server using the Administration Console. A distribution file (.sdn file) is made up of package files (.spk files) that may have dependencies on one another. The Spotfire.Dxp.sdn distribution is the most frequently encountered example of a distribution file and is located in the deployment kit folder TIB_spotdeploy_5.5.0_win\Products\TIBCO Spotfire Distribution. For comprehensive help about how to deploy packages, see the TIBCO Spotfire Deployment and Administration Manual, distributed with the TIBCO Spotfire Deployment distribution.

5.4

Install TIBCO Spotfire for Spotfire Administrator Usage

Some procedures have to be performed on a TIBCO Spotfire Client. Install a TIBCO Spotfire client on a computer and log in using the administrator user you have assigned to verify that the deployment you have created works, and to get access to the Administration Manager and the Library Administration tools.

5.4.1 Manage Licenses and Preferences

To assign licenses, start TIBCO Spotfire, select Tools > Administration Manager, and select the Groups and Licenses tab. See the TIBCO Spotfire Deployment and Administration Manual for details.
TIBCO Spotfire Server 5.5

105 (276)

5 Administration

5.5

Install TIBCO Spotfire Clients on End Users Machines

When all the tasks described above are finished, the Spotfire client can be installed on each Spotfire users computer. See the TIBCO Spotfire Deployment and Administration Manual for comprehensive instructions on how to do this. You must also either start each client and go into the Manage Servers... dialog and add the Server URL, or distribute this URL to all users that they may enter it themselves.

5.6

Enable Data Functions Usage

Spotfire 5.5 features pre-packaged predictive analytic methods in the form of Data Functions. In order to leverage these Data Functions, TIBCO Spotfire Statistics Services needs to be installed and configured. The Data Functions immediately provide useful analytic functionality to Spotfire users. They also provide detailed and flexible templates to help users develop their own Data Functions more quickly and easily. Installing the Data Functions will make these features potentially available to your users. To make the data functions available to users, locate the datafunctions folder in the Spotfire Server installation kit. Copy the file datafunctions.part0.zip (this ZIP file contains the data functions and analysis files) to the configured library Import/Export folder. See Configuring a Specific Directory for Library Import and Export on page 99. When this file is in place, a Spotfire Administrator or a Library Administrator can import these files to the Library.

1 2 3 4 5 6 7 8

To Import the Data Function Files into the Library Start TIBCO Spotfire and log in as a Spotfire Admin. Select Tools > Library Administration. Navigate to the Library folder where you want to import the demo files. For instance, you can create a folder called DataFunctions. Select Import. Click Browse and select the file datafunctions.part0.zip. Click OK. Click OK. Click Close when the dialog states Import Done.

106 (276)

TIBCO Spotfire Server 5.5

5 Administration

5.7

Enable Demo Database Usage

To make the demo database available to users locate the folder called demodat in the Spotfire Server installation kit. Select the oracle or mssql sub-folder depending on your database server, and copy the file within this folder, demo.part0.zip to a shared disk location. See Configuring a Specific Directory for Library Import and Export on page 99. This ZIP file contains analysis files and an information model that links to the demo data. When this file is in place, a Spotfire Administrator or a Library Administrator can import these files to the Library.

1 2 3 4 5 6 7 8

To Import the Demo Files into the Library Start TIBCO Spotfire and log in as a Spotfire Admin. Select Tools > Library Administration. Navigate to the Library folder where you want to import the demo files. For instance, you can create a folder called Demo. Select Import. Click Browse and select the file demo.part0.zip. Click OK. Click OK. Click Close when the dialog states Import Done. A template data source will also be imported with this file. You must use the Information Designer to edit this and supply the URL and login information of your database server for it to work. See the Information Designer help for more information about how to set up and edit data sources.

TIBCO Spotfire Server 5.5

107 (276)

5 Administration

108 (276)

TIBCO Spotfire Server 5.5

6 Monitoring

Monitoring
TIBCO Spotfire Server can be monitored. Reasons for monitoring include detecting problems with the server itself, problems with external systems such as databases and LDAP servers, network problems, misconfigured clients and in some cases malicious behavior. The purpose is typically to reduce down-time, detect and fix problems before users notice them and to eliminate performance bottle necks. The Spotfire Server can be monitored using TIBCO Hawk or any other Java Management Extensions (JMX) compliant monitoring tool, like JConsole, a part of the Java SDK which is bundled with the Spotfire Server. JMX is a Java framework for monitoring and managing applications and devices. It is part of the Java Platform, Standard Edition since version 5.0. See Log User Action on page 113 for information about how to log actions running on the TIBCO Spotfire Server, and also events from TIBCO Spotfire, TIBCO Spotfire Web Player, and TIBCO Spotfire Automation Services.

6.1
1 2 3

Instrumentation
JMX consists of three levels: Instrumentation level: Provides monitoring information and management operations. Agent level: Server that provides applications access to the instrumentation level. Remote Management level: Connectors and adaptors providing access to the agent. TIBCO Spotfire Server runs within the Tomcat application server which provides the basic functionality needed, the server (Agent level) and a Java Remote Method Invocation (Java RMI) connector (Remote Management level). Tomcat provides a rich instrumentation set for monitoring and managing the application server, for instance Tomcat configuration parameters and basic usage statistics. On top of this the Java shipped with Spotfire Server is also heavily instrumented using JMX, providing information about CPU and memory usage, garbage collection and thread pools. The Spotfire Server has been instrumented with the following measures: Note: Also see Log User Action on page 113. Server

Server address (IP) Server hostname Server version Date and time the server was started Uptime time since the server was started, both as a formatted string and in milliseconds since January 1, 1970, 00:00:00 GMT
109 (276)

TIBCO Spotfire Server 5.5

6 Monitoring

Logging

Current log configuration file (configurable) Available log configuration files (read only) Lists all log configuration files in <installationdir>\tomcat\webapps\spotfire\
WEBINF

Number of logging events on warn, error and fatal levels

Logger There may be several of these or none at all, depending on the log configuration.

Log appender name Notifications: Outputs all log statements from a configured log4j appender as JMX notifications

Server Metrics

Number of attachments on the server Number of running Information Services jobs Number of authenticated HTTP sessions

HTTP Status Codes

Number of HTTP response codes representing client or server errors, meaning the 4xx and 5xx ranges returned from the server. Note: Responses in these series may be common, even in a system that works well.

Data Source One entry for each currently running data source on the server, including the servers own data source:

Name URL Configured minimum number of connections Configured maximum number of connections Current number of active connections Current number of idle connections The maximum number of concurrently active connections seen

110 (276)

TIBCO Spotfire Server 5.5

6 Monitoring

6.2

Configuration
Because sensitive information may be provided through JMX and since the Java, Tomcat, and Spotfire Server provide some management capabilities, it is important to restrict the access. The JMX RMI connector is disabled by default; the administrator must enable it. Also consider the authentication, authorization and encryption security features. Authentication The Spotfire Server solution applies the existing database authentication mechanism using a separate database table. Passwords are hashed and the same principals may be used across an entire Spotfire Server cluster. Authentication is enabled by default. Authorization Each user has only read, or read and write permissions. This means that the user can either only read attribute values, or in addition, read and modify the attributes in case they are writable. Authorization is enabled by default. Authorization only works with the default authentication implementation. JMX accounts and credentials are separated from Spotfire accounts and credentials. The JMX accounts are only used for monitoring, since ordinary Spotfire login does not work. Encryption The RMI connector can be configured to encrypt the traffic using SSL. This is recommended since usernames and passwords are otherwise transmitted in plain text. SSL is not enabled by default. It requires a certificate. Firewalls A firewall can be configured to allow traffic to the desired ports. By default the RMI registry and the RMI connector share a common port (1099) to simplify firewall configuration. JMX Configuration Commands The following commands are used to configure and administrate JMX access to the monitoring component.
configjmx createjmxuser deletejmxuser listjmxusers

Configures the JMX RMI connector Creates a new JMX user account Deletes a JMX user Lists all JMX users
111 (276)

TIBCO Spotfire Server 5.5

6 Monitoring

6.3

Example
The procedure to set up JMX monitoring using JConsole is described, this example does not use SSL: 1 2 3 4 5 6 7 8 9 Run the configjmx command: config configjmx enabled=true Import the configuration: config importconfig comment=Enabling JMX
configuration.xml

Provide the configuration tool password. Create a JMX user: config createjmxuser username=MyJMXUser Provide the MyJMXUser password. Provide the configuration tool password to write the user and password to database. Restart the Spotfire Server. Launch the JConsole application. In a default Windows installation: C:\tibco\tss\5.5.0\
jdk\bin\jconsole.exe

In the JConsole New Connection dialog, select Remote Process, enter the <hostname>:1099, and provide the JMX username and password. Comment: To view the Spotfire specifics, see the MBeans tab and the com.spotfire.server domain.

112 (276)

TIBCO Spotfire Server 5.5

7 Log User Action

7
7.1

Log User Action

Introduction
The log user action is a new feature in the 5.5 Spotfire Server. This feature collects information about what the users are doing, for example if a user opens a file from the library, when a user logs in etc. It does not only log actions running on the server, but also events from TIBCO Spotfire, TIBCO Spotfire Web Player, and TIBCO Spotfire Automation Services. All events are collected on the Spotfire Server, and the events that do not originate from the server are sent to the Spotfire Server through a web service. The log user action feature is turned off by default. The log events can be written to files, to a database, or to both. In contrast to the other log files the action log files will not be pruned; instead a new file will be created every day, thus some extra administration is needed to ensure that there is room in the file system. For the database logging there is an option to automatically remove entries which are older than a certain number of hours.

It is possible to analyze the gathered data using Spotfire. For the database there is an Information Model and an analysis file which can be used to start analyzing usage patterns. With the collected data it should be possible to answer many more questions on how the system is used. It will answer questions on who did what, but not static questions like who can do what, but you see when someone gives more rights to someone.

TIBCO Spotfire Server 5.5

113 (276)

7 Log User Action

7.2

What is Being Logged

To decide if you want to enable the log user action feature it is instructive to see what information it provides. The attempt is to log when the user performs a significant action. The log points are separated into different categories; for the categories there are different actions, for example when a user changes password it belongs to the admin category and the action is change_passwd. For every log point there are some generic fields which are shared among log points, these are:
logged_time; machine; user_name; original_time; original_ip; category;action; success; session_id,

And then there are some specific measures for every log point, for example when we log that a user changes password we log uName, meaning the user name. The generic fields are described below.
logged_time machine user_name The time the event was logged. The machine that did the logging. The name of the authenticated user performing the logged action.

original_time The time the event originally was created, this might differ since it can take time for the log event to be written. original_ip category action success session_id From where the call originates. Note: We will check on TCP level, so it might be a proxy that shows up here. The category of the event, for example admin. The action within the category, for example change_passwd. Tells if the operation succeeded or not. For 5.5 the emphasis is on the successful operations. A (unique) id for the session.

Apart from these there are some variable fields. In the database these will fill out id1, id2,arg1,arg2 etc. For the database there are also database views which will have the generic column names altered to the ones in the table below. For the change password there is a specific view, which for Oracle is defined as:
CREATE OR REPLACE VIEW ADMIN_CHANGE_PASSWD AS SELECT LOGGED_TIME, MACHINE, USER_NAME, ORIGINAL_TIME, ORIGINAL_IP, SUCCESS, SESSION_ID, ID1 AS UNAME FROM ACTIONLOG WHERE LOG_CATEGORY = 'admin' AND LOG_ACTION = 'change_passwd'

The following log points exist. If the category has the suffix _pro it means that it an operation coming from TIBCO Spotfire, _wp means that it is coming from the TIBCO Spotfire Web Player, and _as means that it is coming from the TIBCO Spotfire Automation Services. The ones without suffix all originate on the server. It is possible to configure so that only certain categories are logged.

114 (276)

TIBCO Spotfire Server 5.5

7 Log User Action

.
Category Action id1 id2 arg1 arg2 arg3 arg4

admin admin admin admin admin admin admin admin admin auth auth auth auth_as auth_as auth_pro auth_pro auth_wp auth_wp datafunctio n_pro datasource_ pro file_pro info_link info_link info_link

change_passw d create_group create_user group_add_m ember group_remove _member remove_licens e remove_princi pal rename_princi pal set_license impersonate login logout login logout login logout login logout execute execute load create_il get_data load_il

uName gName uName Name Name gName name oldNa me gName uName clientT ype uName uName uName uName uName uName uName unused unused unused library Id library Id library Id path path path path path path duration groupingId sizeb groupi ngId params params clientVer displayName email displayN ame displayN ame gName gName licenseN ame sort newNam e licenseN ame groupingId sort excludingFu nction email email sort sort grouping Id grouping Id

TIBCO Spotfire Server 5.5

115 (276)

7 Log User Action

info_link library library library library library library library library library library library library_as library_pro library_pro library_wp library_wp library_wp

update_il copy create delete export import load_content move remove_perm save_content set_group_per m set_user_perm load close load clone close load

library Id library Id library Id library Id library Id library Id library Id library Id library Id library Id library Id library Id library Id library Id library Id library Id library Id library Id

path path path path path path path path path path path path path path path path path path libraryType libraryType libraryType destPath destPath libraryType libraryType name libraryType gName uName destLibr aryId preSize grouping Id grouping Id grouping Id duration destLibr aryId sort preSize permissi on permissi on postSiz e groupi ngId groupi ngId sizeb destPat h groupi ngId groupi ngId destPat h postSiz e groupi ngId

116 (276)

TIBCO Spotfire Server 5.5

7 Log User Action

The different measures have the following meanings.

clientType clientVer destLibraryId destPath displayName duration email excludingFuncti on gName groupingId The type of client is it, for example TIBCO Spotfire Web Player. The version of the client that is connecting, for example 5.5.0. The destination library id. The destination library path. The display name for a user, for example John Smith. The amount of time the operation/operations took (in ms). The e-mail address. For licenses, this is a subfunction within a license which is not turned on. The Group name. Operations related to the same operation can share a common groupingId. For some operations this is the same as the job-id seen in the other logs. The id of the library item. The license name. The sort of library type is it, for example dxp. query. The name of the entity. The new name. The old name. For certain operations we do not have the exact functionality, but this information can help to decide what has happened. The path. The permission. The size afterwards (in bytes). The size before (in bytes). The size (in bytes). The type it is (user or group). The user name. This is currently not used.

libraryId licenseName libraryType name newName oldName params path permission postSize preSize sizeb sort uName unused

When logging to file, the user john has changed password, can look something like:

TIBCO Spotfire Server 5.5

117 (276)

7 Log User Action

2013-05-07T11:55:36.356+0200;10.100.33.227;john;2013-05-07T11:55:36.3 55+0200;0:0:0:0:0:0:0:1;admin;change_passwd;true;b549dfcf-0059-4d63-b 7d0-f710cc10a3cc;john;null

Another example where a file originally opened from the library has been closed on TIBCO Spotfire:
2013-05-07T11:55:36.356+0200;10.100.33.227;sfal;2013-04-08T16:20:14.2 03+0200;null;library_pro;close;true;22154702-8e44-4a26-a102-f1a63121f 763;4447a4f7-2c33-43f0-9ed7-edafa152969f;/Demo/Baseball Deb

Every log event will be placed on a new row; in the log file semicolon is used as separator; in the database they end up in different columns some are generic and some columns will have different meaning depending on the category and action. When logging to database, there is one more category dblogging. It has three actions:

pruned, when things are removed as a result of the pruning action startup, when we are starting to log (meaning when the server is started) shutdown, when the server is shut down (there is a risk that this is lost if the grace period is too short, but normally it should be there, grace period will be explained later)

7.3

Web Service
To be able to capture log points from TIBCO Spotfire, TIBCO Spotfire Web Player, and TIBCO Spotfire Automation Services there is a web service. It is possible to decide that only certain categories should be logged through the web service. To ensure that no unnecessary SOAP traffic is generated, the clients will check with the server during startup for the active categories. If the feature is not enabled then no extra SOAP calls will be generated. There are three settings on the server. If it should be turned on at all, which categories should be enabled (all will turn on all categories) and a regular expression to decide if logging requests should be accepted or not (.* will accept from any host).

7.4

Log File
As an option, action logging can be directed to a file. In contrast to our other logs, a new file will be created every day. You can see in the log4j configuration files that it uses the DailyRollingFileAppender. Files will never be automatically removed, thus if it is enabled you need to make sure that there is room for these files. Fields are separated by a semicolon, any semicolon in the measures will be replaced with a sentence spacing. The file can be opened directly in TIBCO Spotfire. Example of a log file:
2013-04-08T16:15:35.062+0200;10.100.33.227;pasp;2013-04-08T16:15:35.0 61+0200;10.100.33.209;auth;login;true;259bcfcd-cd75-4757-a41e-99b06e2 8fdb1;TIBCO Spotfire Web Player;5.5.0

118 (276)

TIBCO Spotfire Server 5.5

7 Log User Action

2013-04-08T16:15:38.729+0200;10.100.33.209;pasp;2013-04-08T16:15:36.3 30+0200;::1;auth_wp;login;true;259bcfcd-cd75-4757-a41e-99b06e28fdb1;p asp;null 2013-04-08T16:15:42.029+0200;10.100.33.227;pasp;2013-04-08T16:15:42.0 28+0200;10.100.33.209;library;load_content;true;259bcfcd-cd75-4757-a4 1e-99b06e28fdb1;4447a4f7-2c33-43f0-9ed7-edafa152969f;/PAsp/Baseball Deb;0000000013;0000383230;null 2013-04-08T16:15:43.328+0200;10.100.33.209;pasp;2013-04-08T16:15:41.9 00+0200;::1;library_wp;load;true;259bcfcd-cd75-4757-a41e-99b06e28fdb1 ;4447a4f7-2c33-43f0-9ed7-edafa152969f;/PAsp/Baseball Deb;AnalysisDxp 2013-04-08T16:15:57.720+0200;10.100.33.209;pasp;2013-04-08T16:15:56.3 67+0200;::1;library_wp;close;true;259bcfcd2013-04-08T16:16:19.185+020 0;10.100.33.209;pasp;2013-04-08T16:16:17.541+0200;::1;auth_wp;logout; true;259bcfcd-cd75-4757-a41e-99b06e28fdb1;pasp;null 2013-04-08T16:16:21.104+0200;10.100.33.209;pasp;2013-04-08T16:16:19.9 73+0200;::1;library_wp;close;true;259bcfcd-cd75-4757-a41e-99b06e28fdb 1;4447a4f7-2c33-43f0-9ed7-edafa152969f;/PAsp/Baseball Deb 2013-04-08T16:16:28.287+0200;10.100.33.227;unknown;2013-04-08T16:16:2 8.286+0200;10.100.33.209;auth;logout;true;259bcfcd-cd75-4757-a41e-99b 06e28fdb1;pasp;null

The log files will show up in a subdirectory of the usual logging directory:
<installationdir>/tomcat/logs/actionlogs

7.5

Database Logging
As an option, action logging can be directed to a database. There are many configuration options available for the database logging which will make it possible to tailor the system for your needs. To see how this functionality works it is illustrative to follow how an event is logged.

TIBCO Spotfire Server 5.5

119 (276)

7 Log User Action

1 2 3 4 5 6 7 8 9 10

An event is created. A check is done to see if logging is turned on. A check is performed to see if this category should be logged. It is fed to one or two of our loggers. If file logging is enabled it will be written to the file. A check is made to see if logging should be done towards the database. The database logger will put the event in a fixed size queue (the size is fixed in runtime, but can be configured). If the queue is full it can be configured to wait until there is room in the queue or wait for a configurable time. The chunk worker will wait until there are a configurable number of events available or a certain configurable time has passed. The chunk worker will start up an insert worker. The number of simultaneous insert workers can be configured. If the limit of simultaneous workers is reached it will wait for an insert worker to finish. The insert worker will do a batch insert into the database. As you can see there are several possibilities here to configure the system, if is it very important that everything is logged then you should block for a place in the queue. If there is a high load then you should configure many simultaneous insert workers. On the other hand if you just want to sample the system and you do not want to load a database instance then you could set the number of insert workers to a low number. There is an optional pruner thread which, if enabled, every hour will check if there are events older than a configurable number of hours. The events which are older will be removed. Per default the system will delete events older than 240 hours. If the value is set to 0 then no pruning will take place and your DBA need to administer the growth through some other means, for example by partitioning the table. If there still are events in the queue when the server is about to be stopped, there will be an attempt to try to write remain items on the queue to the database during a grace period. The grace period is also configurable. As mentioned above many parameters of the machinery are configurable. This should make it possible to tune the system for different environments and loads. To help to tune the system there is a JMX (see Monitoring on page 109 for more information about JMX). This JMX bean can answer the following questions:

11

How many more events can be queued (getRemainingQueueCapacity()) How many events are on the queue (getCurrentQueueSize()) How many events have been attempted to be logged (getNumberOfLogged()) How many events have not been put in the database (getNumberOfFailedLogs())
TIBCO Spotfire Server 5.5

120 (276)

7 Log User Action

How many more insert workers can be started (getCurrentNumberOfSpareWorkers()) What is the minimum number of spare insert workers since the server was started, 0 indicates that all possible workers were started at some point (getMinimumFreeWorkers()) How many SQL Exceptions have been encountered (getNumberOfSQLExceptions()) How many items have been pruned from the database (getNumberOfPrunedEntries())

During startup the database logger will try to connect to the database, and if it fails it will try to reconnect with increasing intervals. If no database is available after the start attempts, the server will not run, thus if the functionality is enabled there is another system dependency. If you want to run towards a database then you need to run additional database scripts. These will create a new schema/database for the action logs to make it simpler to for example partition the data table. Everything is logged to the table ACTIONLOG. Then some indices are created, if you do not do searches, then you can omit the indices. If you have them turned on and also have pruning, then your DBA should consider rebuilding the indices periodically. Then there are views created for category and action, these will help to interpret the generic columns. If you do not use the views then you can omit them from the database creation script. For the database there is also an Information Services model and an analysis file, which can be used to get insights into the usage of the system.

7.6

Installation of the Log User Action Feature

Per default nothing is turned on. To turn it on you need to configure it. If you want to run with database logging you also need to run additional installation scripts. If you turn on database logging you can also import a library file which will give an information model and an analysis file. The configuration of this feature has three commands: 1
configactionlogger, this one controls if the functionality should be enabled or not. The

default is that it is turned off. If it is on, then it controls which categories should be logged, it also controls if logging should be directed towards file and/or database. An example where all categories are enabled and we log both to file and database:
config-action-logger --file-logging-enabled=false --database-logging-enabled=true

configactionlogdatabaselogger, this controls the different tuning parameters of the

database logger as well as the database connection information. Example if you only want to run with the default parameters:
TIBCO Spotfire Server 5.5

121 (276)

7 Log User Action

config-action-log-database-logger --database-url= "jdbc:tibcosoftwareinc:oracle://some.oraserver.com:1521;SID=orcl" --driver-class="tibcosoftwareinc.jdbc.oracle.OracleDriver" --username="spotfire_actionlog" --password="xxxxx"

If you want to log to a database then you need to run scripts which will create a new database/schema. These are available in the installation kit in these folders:
./scripts/mssql_install/actionlog ./scripts/oracle_install/actionlog

Here the bat or sh file needs to be edited. The information is the same as for the ordinary creation scripts. For Oracle a new schema is created for the spotfire_actionlog user. If you want to use the information layer later then you should not change this user. For Microsoft SQL-server the database will be called spotfire_actionlog. If you want to use the information layer you should not change this name. In the same folder there is a library logged_user_actions_ora.part0.zip (for Oracle) or logged_user_actions_mssql.part0.zip (for Microsoft SQL Server). This file needs to be copied to the library import folder (<installation dir>/tomcat/application data/ library/) and then imported into the library using the library manager. This library export contains an information layer as well as an analysis file. To be able to use the file you need to edit the datasource with the connection information to the schema/ database. Use Information Designer and select the Datasource tab, right click on the logged_user_actions_datasource, select edit. Then edit the connection information. 3
configactionlogwebservice, this controls which categories that are actually logged

and also limit the clients that can log using the web service. Example: enable all categories from all hosts:
config-action-log-web-service --allowedHosts=".*" --categories="all"

Then the configuration needs to be uploaded to the database and the server should be recycled. It is also possible to configure the functionality through the Configuration Tool.

122 (276)

TIBCO Spotfire Server 5.5

7 Log User Action

7.7

Some Comments
The information above about log categories, actions, and measures should not be considered as a stable API which will remain unchanged between releases. All things can change, but it is more likely that we will add more actions and add measurement columns to existing log points. The log points represents what is happening on the system, there might be a couple of cases where what is shown in the log can feel contra intuitive, for example when using NTLM you will see more logins, if you see what is happening on the network you will see that there are actually several logins happening during a normal session. Another case is when a session dies, there is a maximum life span for a session. Here you will see an event even if the user has not actively made any operation. You can also see that

TIBCO Spotfire Server 5.5

123 (276)

7 Log User Action

there might not be a session when these events are logged, because the session has died. If you are logging to a database then it might be a good idea to involve your DBA to regularly monitor the usage and see if indices should be rebuilt or dropped, if pruning is not turned on then manual pruning or partitioning must eventually take place. Files from a previous release take a certain path through the code. For certain older files the clone operation on the web player might not be logged.

7.8

TIBCO Spotfire Server and the Different Databases/Schemas

It could be worth to point out that there are several kinds of databases or schemas that the server connects to.

Its own database which stores all the information like preferences, library items etc. The data sources that the server makes JDBC connections to retrieve data for analysis, through Information Services. One of the possible data sources is the demo data source which can be created at the same time as the Spotfire database. The new action log data base/schema, which is created if you want to direct the action logs to a database. It is a very simple structure with basically one table and different which can help to analyze the content. It is separate from the Spotfire database to allow since it is a public table and you might want to handle pruning in a specific way.

124 (276)

TIBCO Spotfire Server 5.5

8 Upgrades

Upgrades
There are four different upgrade scenarios for the TIBCO Spotfire Server:

Upgrade to version 5.5 from a previous version of TIBCO Spotfire Server, version 3.0 or higher Migration from Spotfire Analytics Server 10.1 Upgrade between service pack versions Applying hotfixes

Each upgrade scenario and related tasks are described in separate sub-chapters.

8.1

Upgrade to 5.5 from a Previous Version of TIBCO Spotfire Server

This section describes upgrades to TIBCO Spotfire Server 5.5 from a TIBCO Spotfire Server 3.0 or higher. If you intend to upgrade your Spotfire Server from version 3.0 or later to 5.5, use the Spotfire Server Upgrade tool. It upgrades the Spotfire database to the current version, and, if selected, copies certain files from an old installation of Spotfire Server to the Spotfire Server 5.5 installation directory. Note: After the Spotfire database is upgraded, older versions of Spotfire Server will not be able to connect to it. Therefore, stop any older Spotfire Servers connected to the Spotfire database before beginning an upgrade. If you intend to copy information from the old version, do not un-install it until Spotfire Server 5.5 is in place. Note: The upgrade will perform a validation of LDAP configurations. If an invalid LDAP configuration is found, the upgrade will fail. If so, go back to your previous installation, correct the error and perform the upgrade again. Note: When upgrading from version 3.x.x or 4.5.x to 5.0 or later, a new "UTC_TIME" database view will be created for the Spotfire database. This is typically performed by the upgrade tool, but may be a manual step if the database user lacks sufficient permissions. If so, you will be given instructions by the upgrade tool and may need assistance from your DBA.

8.1.1 Install Spotfire Server

The Spotfire Server Upgrade tool is installed with the Spotfire Server. First install Spotfire Server 5.5. See Install Spotfire Server on page 23. Note: If you are using LDAPS, and if the CA certificate is not included in the cacert file by default; you must import the CA certificate used to issue the LDAP server's certificate according to the instructions in section Configuring LDAPS on page 92, before running the upgrade tool.
TIBCO Spotfire Server 5.5

125 (276)

8 Upgrades

8.1.2 Run the Upgrade Tool Interactively

HAVE YOU BACKED UP YOUR SPOTFIRE DATABASE? Before you run the upgrade tool, it is very important that you make sure you have a working backup of your Spotfire database. ARE YOU USING MICROSOFT SQL SERVER WITH WINDOWS INTEGRATED LOGIN? 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. In the Spotfire Server 5.5 installation directory <5.5.0installdirectory>\tools\upgrade you can find the files upgradetool.bat (Windows) and upgradetool.sh (Unix). Run the tool for your operating system from a command line prompt. It can also be launched in the last step of the Spotfire Server installer. Note: If you are upgrading a cluster of Spotfire Servers, run the upgrade tool on each server. The Spotfire database will be updated the first time you run the upgrade tool. The upgrade tool consists of a number of panels which will prompt you for information regarding your 3.x, 4.5 or 5.0 installation and your 5.5 installation.

Running the upgrade tool: The TIBCO Spotfire Server 5.5 Upgrade panel is displayed. It provides a reminder to back up or clone the Spotfire database. Click Next.

The File Locations panel is displayed. It provides new information and the choice to copy, or not to copy, an existing configuration. If you have file access to an old installation, you can select the X.X.X installation option and enter the path to its installation directory, for instance: C:\tibco\tss\5.0 or /opt/tss/5.0 Note: If there are changes needed after upgrade, for example, port configuration or location of SSL certificate, manually edit the server.xml file, located under the <Spot fireServerInstallDir>\tomcat\conf folder. If you select to not copy configuration, you will have to enter all information manually in the following panels. Click Next.

The Database Type and Driver panel is displayed. If you selected to copy an existing configuration, you will not see this panel.

126 (276)

TIBCO Spotfire Server 5.5

8 Upgrades

Specify the database and database driver you are using. If you select a database driver type that is not installed in the Spotfire 5.5 installation directory the message The selected driver must be installed manually will be displayed. Install the selected driver manually by placing it in the <5.5.0installdirectory>/tomcat/lib directory and restart the upgrade tool. Comment: If you select a database driver type that is not installed and click next, the Database Drivers Not Installed panel is displayed, informing that the upgrade tool cannot find a suitable database driver to connect to the database. This only happens if the selected database driver in the previous panel is not installed. If this occurs; click Done to exit the upgrade tool, install the database driver and start the upgrade tool again. If there are no database driver issues, you will not see this panel. Click Next to continue. 4 The Database Connection Information panel is displayed. If you selected to copy configuration, the information on this panel will be populated. Select the Integrated login checkbox if your database server uses integrated login, like Windows authentication, to disable the Username and Password fields.

Provide the 3.x Spotfire database Connection string, Username, and Password.

Click Next. 5 The Additional Information panel is displayed if upgrading from 3.x or if not to copy configuration" was selected in step 2. Set configuration tool password, encryption password and server name. Create a Configuration Tool password to be used when configuring the 5.5 server. Click Next. 6 The User Directory Configuration panel is displayed if LDAP User Directory mode or Windows NT User Directory mode is used. Select a domain name style (DNS or NetBIOS) and a default domain. Note : Make sure to select an accurate domain name style for your system, See Authentication and Post-Authentication Filter on page 54. 7 The Summary panel is displayed, listing the settings chosen before execution. Click Upgrade. 8 The TIBCO Spotfire Server 5.5 Upgrade panel is displayed with a result message.

Following a successful upgrade: The database has been upgraded to TIBCO Spotfire Server 5.5 format or The database has already been upgraded to TIBCO Spotfire 5.5 format, the latter indicating that the database was already in the 5.5 format. Click Finish. If the tool encountered problems, click Next to see the Upgrade Issues panel. The issues are saved in the indicated log file. You may have to correct them manually. Click Finish.
127 (276)

TIBCO Spotfire Server 5.5

8 Upgrades

8.1.3 Run the Upgrade Tool Silently

On a server without a Graphical User Interface, you will need to run the upgrade tool silently. 1 2 3 4 Open the silent.properties file from <5.5.0installdirectory>/tools/upgrade Update silent.properties with the correct parameter values. There are comments throughout the file for guidance. Only the from parameter is mandatory. Open a command prompt. Optional: To see the parameters the upgrade tool will use:

On Windows, type: upgradetool.bath On Linux, type: upgradetool.shh

Response: Response: The parameters are listed in the command prompt. 5 Run the upgrade tool silently:

On Windows, type: upgradetool.batsilentsilent.properties On Linux, type: upgradetool.shsilentsilent.properties

Press Enter.

8.1.4 Start the Spotfire Server

When the upgrade tool has completed and you have verified that there are no issues with the upgrade, start the Spotfire Server. See Start and Stop the Spotfire Server on page 102.

8.1.5 Deploy Client Packages

For Spotfire users to have their old clients automatically upgraded to version 5.5 upon next start, deploy Spotfire 5.5 packages to the server. 5.5 packages must be deployed to the Spotfire Server before you can log in to it with a 5.5 client. Refer to the TIBCO Spotfire Deployment and Administration Manual. If you are running TIBCO Spotfire Web Player, Automation Services, or any add-ons to the Spotfire products, also deploy these upgraded packages to the server.

8.1.5.1 Multiple Deployment Areas Introduced in Spotfire Server 5.5

Starting with TIBCO Spotfire Server 5.5, the notion of Multiple Deployment Areas is introduced. This makes it is possible to create an unrestricted number of deployment areas that can be assigned to groups. This gives a fine grained control over which users get access to which deployments. Handling of multiple deployment areas, assigning

128 (276)

TIBCO Spotfire Server 5.5

8 Upgrades

them to groups etc is done in the Spotfire Administration Console. See the Spotfire Administration Console help for more information. In a system that has been upgraded to 5.5, there will be two deployment areas named Production and Test. The Production deployment area is by default set to the default deployment area, and all existing users will get the packages deployed there. To get the old behavior, with a production and a test deployment area and where users who previously had access to the test deployment area still get their packages from the test area, you need to deploy client packages to the test deployment area as well. Then assign this area to a group in the Spotfire system that you for instance name "test and make sure the users who previously had access to the test area are members of the test group. Note: Make sure that users who shall get the test packages only have access to the test area and are not members of the Administrator or Deployment Administrator groups since those groups have access to all areas. If running a 5.0 or earlier client version, a user who has access to more than one deployment area gets the default deployment area.

8.1.6 Upgrade Spotfire Clients

Start a TIBCO Spotfire client and log in to the Spotfire Server. Make sure that the client is upgraded with the new deployment. Verify that the Spotfire library and information model are accessible and work as they did before the upgrade. If you are running the Web Player, also upgrade the Web Player with the deployed packages. Refer to the TIBCO Spotfire Web Player Installation and Configuration Manual for instructions on how to do this.

8.1.7 Uninstall Old Spotfire Server Version

Once you have verified Spotfire Server configuration, deployed client packages and verified the functionality of the clients, you may safely uninstall the old Spotfire Server. See Uninstalling the Spotfire Server on page 135.

8.2

Migration from Spotfire Analytics Server 10.1

If you are running Spotfire Analytics Server 10.1, you will first need to perform a migration to Spotfire Server 3.3 to migrate information from your Spotfire Analytics Server 10.1 databases to your Spotfire Server 3.3 database. After the migration, an upgrade to TIBCO Spotfire 5.5 can be performed. Please contact Spotfire Customer Support to perform the migration.

TIBCO Spotfire Server 5.5

129 (276)

8 Upgrades

8.3

Upgrade Between Service Pack Versions

Upgrades between service pack versions, for example from 5.0.0 to 5.0.1, shall be performed by applying the latest hotfix and not by running the service pack installer. Go to http://support.spotfire.com/patches_spotfireserver.asp to download the latest hotfix. Installation instructions for each hotfix are included in the package. For more information, see Hotfix installation on page 27.

8.4

Applying Hotfixes
Go to http://support.spotfire.com/patches_spotfireserver.asp to download the latest hotfix. Installation instructions for each hotfix are included in the package. For more information, see Hotfix installation on page 27.

130 (276)

TIBCO Spotfire Server 5.5

Backup and Restore

Backup and Restore

To enable recovery after a crash or disaster in your Spotfire system, it is important that information stored in the system is backed up. Most of this information is stored in the Spotfire database, but some of it is stored on the Spotfire Server(s) and the Spotfire Web Player server(s). 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 with the database. Refer to the database documentation for instructions on how to perform backups. One can only restore to a machine running the same operating system as the backed up system, since there is a bundled Java runtime with binaries for a specific architecture. Back up each server in the cluster. 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. The following sections describe what needs to be backed up.

9.1

Spotfire Database
The most important part of the Spotfire system is the Spotfire database. It contains tables which store the state of the server, for example the library, preferences, and deployments. Most of the Server configuration is also stored in the database. Even if only the database has been backed up, it is still possible to restore most of the functionality after a crash. It is therefore vital that you have a valid and current backup of the Spotfire database. Note: Verify your backups.

9.2

Spotfire Server
A small set of configuration is unique for each Spotfire Server and it is stored on the actual Spotfire Server rather than in the database. This includes information about how the Spotfire Server connects to the Spotfire database, which ports the server should listen to, authentication methods such as Kerberos etc. During installation the server files are essentially all placed in the installation directory. It should be sufficient to back up this directory, of course it is possible to back up the entire file system. Once a server has been configured or hotfixed there are no further persistent changes. Log files and other temporary files will change, but a restored backup will have the same functionality. The configuration which is not in the database includes:

Listening ports configuration (server.xml on page 157 for more information).

131 (276)

TIBCO Spotfire Server 5.5

Backup and Restore

Information about how to connect to the Spotfire database (see the section Database Connection URL Examples on page 163). Logging configuration (see the section Log Files on page 155). Memory configuration (see the section Modifying the Virtual Memory on page 138). HTTPS (see the section Configuring HTTPS on page 88). Authentication such as Kerberos or Client Certificates Database drivers. Any other advanced configuration performed in Advanced Procedures on page 137. When performing advanced configuration, you should always take backup into consideration.

Whenever you make any configuration changes or have applied a server hotfix, you should also perform a backup of the Spotfire Server installation directory. Windows Installations On Windows installations, there is functionality which will not be restored by only recovering the server installation directory:

Windows Service Uninstall functionality Start Menu shortcuts

The Windows Service can be (re-)installed using the bat file service.bat located in the <installationdir>\tomcat\bin directory. Run it from a command line with the following arguments: C:\tibco\tss\5.5.0\tomcat\bin>service.batinstall Uninstallation can be done by removing the service and simply remove the installation directory. The Start Menu shortcuts can be backed up by copying them to the server installation directory, back that up, and when restoring, copying these files to the start menu directory. Unix and GNU/RPM Linux Installations On Unix and GNU/RPM Linux installations, no essential data is placed outside the installation directory by the Spotfire Server. If you have a startup scripts for the server, it will need to be recreated. Network Considerations If you are using Kerberos you should note that configuration needed for this to work is tied to a specific machine and cannot be copied easily to a new one. You should also consider any other conditions in your environment and their implications, such as IP addresses and firewall rules, LDAP restrictions, and anything else that might affect getting a system back up and running.

132 (276)

TIBCO Spotfire Server 5.5

Backup and Restore

9.3

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 able 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 get a functional environment by installing a new Spotfire Server, make sure that it can connect to the database, and configure the things which are stored locally.

TIBCO Spotfire Server 5.5

133 (276)

Backup and Restore

134 (276)

TIBCO Spotfire Server 5.5

10 Uninstallation

10

Uninstallation
A complete uninstallation requires two steps: Uninstalling the TIBCO Spotfire Server and removing the database. The procedures for Windows, RPM Linux and Solaris, and the actions for SQL Server and Oracle respectively are described in this chapter. 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. The installer will remove the installation folder and all its subfolders.

10.1 Uninstalling the Spotfire Server

10.1.1 Windows
Interactive Uninstallation Uninstallation is performed through the regular Windows procedure selecting: Start > Control Panel > Programs and Features > Uninstall or change a program and then right-clicking TIBCO Spotfire Server 5.5 and selecting Uninstall. After successful uninstallation, only user modified files remain on the machine (such as custom JDBC drivers). Silent Uninstallation Run the MSI mechanism as follows:
msiexec.exe /qn /x {20E1FAD06BE04B9A82E42F37453A0A7B}

10.1.2 RPM Linux

Uninstallation is performed via the command: rpmetss5.5.0 After a successful uninstallation, only modified files in tomcat/conf remain.

10.1.3 Solaris
An uninstallation application is created when installing: <installation dir>/installer/ uninstaller/Uninstall_TIBCO_Spotfire_Server_5.5. Run the application to uninstall. Remove the startup script /etc/init.d/tss manually if you have installed it. Also make sure to remove the symbolic links in the appropriate runlevel directories (for example /etc/rc2.d).

TIBCO Spotfire Server 5.5

135 (276)

10 Uninstallation

10.2 Removing the Database

In the scripts/oracle_install/utilities and scripts/mssql_install/utilities folders on the Spotfire Server installation kit, there are a number of scripts that can be used to remove the Spotfire and Demo databases. Before you run the script, open it in a text editor and edit the variables set during database preparation. See the section Prepare the Database on page 17 for detailed information about these variables. WARNING Removing the database deletes all user data and most TIBCO Spotfire Server configurations permanently. Microsoft SQL Server

drop_databases.bat: If you are using database authentication with your Microsoft

SQL server.

drop_databases_ia.bat: If you are using Windows Integrated Authentication with your Microsoft SQL Server.

Oracle

drop.databases.bat: If you are running Oracle on a Windows server. drop_databases.sh: If you are running Oracle on a Unix server.

136 (276)

TIBCO Spotfire Server 5.5

11 Advanced Procedures

11

Advanced Procedures
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, refer to the documentation for the specific technology.

11.1 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 to run:

create_server_db.sql populate_server_db.sql create_server_user.sql

Note: Demo SQL scripts are only necessary if you want to install the demo database tables shipped with the Spotfire Server.

create_demotables.sql create_demo_user.sql

All the SQL files in the folder demodata

Read through the create_databases script to understand how they work. Below are some notes regarding the supported database server types. Oracle When populating a Spotfire database on an Oracle Server the create_databases script passes certain variables to these scripts. These variables include:

ROOTFOLDER CONNECTIDENTIFIER SERVER_DATA_TABLESPACE SERVER_TEMP_TABLESPACE

When you run the SQL scripts manually, you must make sure to pass these variables along to the scripts.

TIBCO Spotfire Server 5.5

137 (276)

11 Advanced Procedures

Microsoft SQL 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.

11.2 Resizing Temporary Tablespace

The tablespaces/database files for Spotfire Server using Oracle/MSSQL Database uses autoextend/autogrowth by default. If this is inappropriate for your needs alter these 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.

11.3 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. Note: Every Java has a specific upper limit for how much memory it can handle. This is a concern mainly for 32 bit Java. If the memory allocation exceeds this limit, Java may not start. To be able to allocate more memory, install the 64 bit version of the Spotfire Server.

1 2

To set up the start script when not running as a Windows service: Open the file <installationdir>/tomcat/bin/setenv.bat/.sh in a text editor. Locate the line that sets the variable JAVA_OPTS:
set JAVA_OPTS=server XX:+DisableExplicitGC XX:MaxPermSize=256M Xms512M Xmx1536M

or
JAVA_OPTS="server XX:+DisableExplicitGC XX:MaxPermSize=256M Xms512M Xmx1536M"

3 4

Alter the -xms and the -Xmx values Xms512MXmx1536M to the amount of memory you wish to allocate. Restart the server. To set up the start script when running as a Windows service: Stop the TIBCO Spotfire Server service Go to the <installationdir>/tomcat/bindirectory
TIBCO Spotfire Server 5.5

1 2
138 (276)

11 Advanced Procedures

3 4 5 6 7 8

Run the command: service.batremove Edit the <installationdir>/tomcat/bin/service.bat file. Look for the entries: JvmMs 512JvmMx1536 Alter 512 and/or 1536to suitable memory values (in MB). Run the command: service.batinstall Start the TIBCO Spotfire Server service.

11.4 Data Source Templates

One feature of the Spotfire system is the ability to create information links, easy-touse 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 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 using the configuration tool. 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 140. The following data source templates are available by default:

Oracle(DataDirectdriver) MicrosoftSQLServer(DataDirectdriver) Teradata Sybase(JTDS) Sybase(DataDirect) Sybase SQLServer2005 SQLServer(JTDS) SQLServer(DataDirect) SQLServer SAS/SHARE Composite Oracle(delegatedKerberos) Oracle(DataDirect) Oracle MySQL5 MySQL(DataDirect) MySQL DB2(DataDirect) DB2

When adding more data source templates, they can be based on the following types:

Note: For the MySQL5 vendor 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: Locate the following section:
<connection-properties> <connection-property>

TIBCO Spotfire Server 5.5

139 (276)

11 Advanced Procedures

<key>useDynamicCharsetInfo</key> <value>false</value> </connection-property> </connection-properties>

and add the following within the connectionproperties tag:

<connection-property> <key>noDatetimeStringSync</key> <value>true</value> </connection-property> <connection-property> <key>zeroDateTimeBehavior</key <value>convertToNull</value> </connection-property>

This is due to a restriction in MySQL5 that has to do with null values in TIMESTAMPS.

11.4.1 Handling Data Source Templates

If you add a data source template that does not use the pre-installed DataDirect driver, you must manually install this driver on each Spotfire Server in the cluster before you restart the cluster. Download the appropriate driver JAR file and place it in the <instal lationdir>/tomcat/lib folder of each server.

To add a new data source template: Use the command add-ds-template on page 177. To enable, modify or disable a data source template: For a data source template to become available in the Information Designer, it must be enabled. Use the command modify-ds-template on page 246.

To remove a data source template: Verify that no data sources use the data source template before you remove it. If a data source template is removed, all data sources using that template will stop working. Use the command remove-ds-template on page 247.

11.4.2 XML Settings

The table below shows all settings available. Only the first three are mandatory settings:

type-name driver connection-url-pattern

140 (276)

TIBCO Spotfire Server 5.5

11 Advanced Procedures

If left out, all other settings will automatically use their default values.
Setting Description

typename driver

A unique name for the configuration. The JDBC driver Java class used for creating connections.

connectionurlpattern A pattern for the connection URL. The URL syntax is driver specific. pingcommand connectionproperties metadataprovider A dummy command to test connections. Default: SELECT1 JDBC connection properties. Java class that provides database metadata. See Spotfire Technology Network. Default: BasicJDBCMetadataProvider sqlfilter Java class that generates SQL. See Spotfire Technology Network. Default: BasicSQLFilter Java class that handles SQL execution. See Spotfire Technology Network. Default: BasicSQLRuntime A fetch size specifies the amount of data fetched with each database round trip for a query. The specified value is shown as the default value in Information Designer. May be changed at instance level. Default: 10000 A batch size specifies the amount of data in each batch update. The specified value is shown as the default value in Information Designer. May be changed at instance level. Default: 100 The maximum length of a database column name. This limit is used when creating temporary tables. Default: 30 Specify which table types to retrieve. Default: TABLE,VIEW Tells if the driver supports catalogs. Default: true Tells if the driver supports schemas. Default: true Tells if the driver supports stored procedures. Default: false

sqlruntime

fetchsize

batchsize

maxcolumnname length tabletypes supportscatalogs supportsschemas supportsprocedures

TIBCO Spotfire Server 5.5

141 (276)

11 Advanced Procedures

supportsdistinct supportsorderby columnnamepattern tablenamepattern schemanamepattern catalognamepattern procedurename pattern columnaliaspattern stringliteralquote maxinclausesize

Tells if the driver supports distinct option in SQL queries. Default: true Tells if the driver supports order-by option in SQL queries. Default: true Determines how a column name is written in the SQL query. Default: $$name$$ Determines how a table name is written in the SQL query. Default: $$name$$ Determines how a schema name is written in the SQL query. Default: $$name$$ Determines how a catalog name is written in the SQL query. Default: $$name$$ Determines how a procedure name is written in the SQL query. Default: $$name$$ Determines how a column alias is written in the SQL query. Default: $$name$$ The character used as quote for string literals; SQL-92 standard. The maximum size of an SQL IN-clause. Larger lists are split into several clauses that are OR:ed together. Default: 1000 A temporary table is used when executing an SQL query, where total size of a condition list is larger than this threshold value. A Data Base Administrator may prefer a lower value than the default. Depends on the maximum SQL query size. Default: 10000 If true, an SQL IN-clause will be expanded into OR conditions. Default: false Determines how a table expression is written in the SQL query; catalog and schema may be optional (surrounded by brackets). Default: [$$catalog$$.][$$schema$$.]$$table$$ Determines how a procedure expression is written in the SQL query. Default: [$$catalog$$.][$$schema$$.]$$procedure$$ Integer representing the jdbc type identifying a table returned form a procedure as defined by java.sql.Types. Default: 0 Display name for tables from procedure. This is currently not visible to the user in any UI. Default: null

conditionlist threshold

expandinclause tableexpression pattern procedureexpression pattern proceduretablejdbc type proceduretabletype name

142 (276)

TIBCO Spotfire Server 5.5

11 Advanced Procedures

dateformat expression

An expression that converts a date field to a string value on the format: YYYYMMDD, for example, 20021119. Used in WHERE and HAVING clauses. The tag $$value$$ is a placeholder for the date field. Default: $$value$$ An expression that converts a date literal on the format YYYYMM DD to a date field value. Used in WHERE and HAVING clauses. The tag $$value$$ is a placeholder for the date literal. Default: '$$value$$' An expression that converts a time field to a string value on the format: HH:MM:SS, for example 14:59:00. Used in WHERE and HAVING clauses. The tag $$value$$ is a placeholder for the time field. Default: $$value$$ An expression that converts a time literal on the format HH:MM:SS to a time field value. Used in WHERE and HAVING clauses. The tag $$value$$ is a placeholder for the time literal. Default: '$$value$$' An expression that converts a datetime field to string value on the format: YYYYMMDDHH:MM:SS, e.g 2002111914:59:00. Used in WHERE and HAVING clauses. The tag $$value$$ is a placeholder for the date-time field. Default: $$value$$ An expression that converts a date-time literal on the format YYYY MMDD HH:MM:SS to a date-time field value. Used in WHERE and HAVING clauses. The tag $$value$$ is a placeholder for the date-time literal. Default: '$$value$$' 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). 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 match-length is used. Default: VARCHAR($$value$$) VARCHAR(255) INTEGER BIGINT REAL DOUBLEPRECISION DATE TIME TIMESTAMP Determines how to format a temporary table name in an SQL command. Default: $$name$$

dateliteralformat expression

timeformat expression

timeliteralformat expression

datetimeformat expression

datetimeliteral formatexpression

javatosqltype conversions: String Integer Long Float Double Date Time DateTime temptablename pattern

TIBCO Spotfire Server 5.5

143 (276)

11 Advanced Procedures

createtemptable command

SQL commands for creating a temporary table. This is used to store filter values (when more than conditionlistthreshold) and to store result from subqueries. The syntax may vary between databases. $$name$$ is a placeholder for the table name. $$column_list$$ is a placeholder for a column list on the format (nametype,nametype,...). Default: CREATETEMPORARYTABLE$$name$$$$column_list$$ SQL commands for deleting a temporary table. The syntax may vary between databases. $$name$$ is a placeholder for the table name. Default: DROPTABLE$$name$$ Default value data source authentication. (boolean). This value can be set (overridden) in the Information Interaction Designer. Default: false Threshold when LOB values used as parameters in a WHERE clause, must be written in temporary tables. The default means no limit. Default: 1 The default generated SQL uses the Oracle way with (+) to indicate joins. If this setting is set to true an attempt is made to rewrite it to standard ANSII format, making it possible to run on non Oracle databases Default: false 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). Applicable only if datasource authentication is set to true. Default:86400 (24 hours)

droptemptable command

datasource authentication lobthreshold

useansiistyleouter join

credentialstimeout

11.4.2.1 Defining JDBC Connection Properties

The optional <connection-properties> parameter block in the <jdbc-type-settings> 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 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 <jdbc-type-setting> 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.

144 (276)

TIBCO Spotfire Server 5.5

11 Advanced Procedures

Example: Defining JDBC Connection Properties for data source of type oracle. This example creates an encrypted connection to the database.
<jdbc-type-settings> <type-name>oracle</type-name> <driver>oracle.jdbc.OracleDriver</driver> <connection-urlpattern>jdbc:oracle:thin:@&lt;host&gt;:&lt;port1521&gt;:&lt;sid&gt;</ connection-url-pattern> <ping-command>SELECT 1 FROM DUAL</ping-command> <connection-properties> <connection-property> <key>oracle.net.encryption_client</key> <value>REQUIRED</value> </connection-property> <connection-property> <key>oracle.net.encryption_types_client</key> <value>( 3DES168 )</value> </connection-property> <connection-property> <key>oracle.net.crypto_checksum_client</key> <value>REQUIRED</value> </connection-property> <connection-property> <key>oracle.net.crypto_checksum_types_client</key> <value>( MD5 )</value> </connection-property> </connection-properties> ... </jdbc-type-settings>

11.4.2.2 Advanced Connection Pool Configuration

Information Services uses the same underlying connection pool implementation as the Spotfire Server uses for connecting to its own database. The following special parameters are available to configure some of the aspects of that connection pool:

spotfire.pooling.data.source.scheme Corresponds to the poolingscheme parameter. SeeDatabase Connectivity on

page 161.

spotfire.pooling.data.source.connection.timeout Corresponds to the connectiontimeout parameter. SeeDatabase Connectivity

on page 161.

spotfire.pooling.data.source.login.timeout Corresponds to the logintimeout parameter. SeeDatabase Connectivity on

page 161.

spotfire.kerberos.login.context Corresponds to the kerberoslogincontext parameter.

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.

TIBCO Spotfire Server 5.5

145 (276)

11 Advanced Procedures

Example: Configuring a connection pool for Oracle databases

<jdbc-type-settings> <type-name>oracle</type-name> <driver>oracle.jdbc.OracleDriver</driver> <connection-urlpattern>jdbc:oracle:thin:@&lt;host&gt;:&lt;port1521&gt;:&lt;sid&gt;</ connection-url-pattern> <ping-command>SELECT 1 FROM DUAL</ping-command> <connection-properties> <connection-property> <key>spotfire.pooling.data.source.scheme</key> <value>WAIT</value> </connection-property> <connection-property> <key>spotfire.pooling.data.source.connection.timeout</key> <value>1800</value> </connection-property> <connection-property> <key>spotfire.pooling.data.source.login.timeout</key> <value>30</value> </connection-property> </connection-properties> ... </jdbc-type-settings>

11.4.2.3 Using Kerberos Authentication for JDBC Data Sources

Configuration of Kerberos authentication for JDBC data source is performed in a similar way as for the connection to the Spotfire database. See section Using Kerberos to log in to the Spotfire Database on page 93 for more information. Example: Configuring a connection pool for Oracle databases
<jdbc-type-settings> <type-name>oracle</type-name> <driver>oracle.jdbc.OracleDriver</driver> <connection-urlpattern>jdbc:oracle:thin:@&lt;host&gt;:&lt;port1521&gt;:&lt;sid&gt;</ connection-url-pattern> <ping-command>SELECT 1 FROM DUAL</ping-command> <connection-properties> <connection-property> <key>spotfire.kerberos.login.context</key> <value>DatabaseKerberos</value> </connection-property> <connection-property> <key>oracle.net.authentication_services</key> <value>( KERBEROS5 )</value> </connection-property> </connection-properties> ... </jdbc-type-settings>

146 (276)

TIBCO Spotfire Server 5.5

11 Advanced Procedures

11.4.2.4 Using Kerberos Authentication with Delegated Credentials

To make users authenticate to different data sources with their own single sign-on login information, the server can delegate the user authentication to the data source. This is only possible if you use the Kerberos single sign-on method. In order to set this up, there are a number of steps that must be taken. Each of these steps is described in detail below. Set up Kerberos authentication as described in the section Kerberos Authentication on page 64. Make sure that users are able to log in with this method. Grant the Spotfire Server service account used for client authentication the right to delegate client credentials. Create a JDBC data source template using Kerberos login Grant the Spotfire Server Service Account the Right to Delegate Client Credentials If your Window Domain is using Windows Server 2003 or later, grant constrained delegation rights to the service account: Only the specified accounts can be delegated by the service account. If you are using an earlier version of Windows Server or cant use this method, grant unconstrained delegation rights. Both methods are described below. Note: In order for delegation to work, you must also ensure that no client user account in the domain has the setting Account is sensitive and cannot be delegated. By default, this is not set.

1 2 3

1 2 3 4 5

To enable constrained delegation: On the Domain Controller, select Start > Programs > Administrative Tools. Select Active Directory Users and Computers. Locate the account. Right-click the account name, and then click Properties to open the account properties. On the Delegation tab, select Trust this user for delegation to specified services only. Note: The Delegation tab is only visible for accounts that SPNs are mapped to. Select Use any authentication protocol. Click Add Click Users or Computers and select the account that the TIBCO Spotfire Server has a keytab for and the SPNs are mapped to. Select all services that apply and click OK. Click Apply.
147 (276)

6 7 8 9 10

TIBCO Spotfire Server 5.5

11 Advanced Procedures

1 2 3 4 5 6

To enable unconstrained delegation for a on a Domain Controller in Windows 2000 Mixed or Native Mode: On the Domain Controller, select Start > Programs > Administrative Tools. Select Active Directory Users and Computers. Locate the account. Right-click the account name, and then click Properties to open the account properties. Select the Account tab and select Account is trusted for delegation in the Account Options list. Click Apply. To Enable Unconstrained Delegation on a Domain Controller in Windows Server 2003 Mode: On the Domain Controller, select Start > Programs > Administrative Tools. Select Active Directory Users and Computers. Locate the account. Right-click the account name, and then click Properties to open the account properties. On the Delegation tab, select Trust this user for delegation to any service (Kerberos only), and then click Apply. Note: The Delegation tab is only visible for accounts that SPNs are mapped to. Create an Information Services data source template using Kerberos login The default Information Services Data Source templates shipped with Spotfire Server are not configured to use Kerberos. You must therefore create a new data source template based on one shipped.

1 2 3 4 5

1 2 3

To Create an Information Services data source using Kerberos login: Use the listdstemplate (page 235) command to list the existing data source templates and select one that matches the database you are setting up, for example Oracle. Use the exportdstemplate (page 222) command to export the definition of the selected data source template. In a text editor, open the exported definition file. Add the JDBC connection property key spotfire.connection.pool.factory.data.source with the value kerberos.data.source within the connectionproperties element. If there is no connectionproperties element, create one.

148 (276)

TIBCO Spotfire Server 5.5

11 Advanced Procedures

There may also be other connection properties you must add - consult the documentation of the database server for more information. See Defining JDBC Connection Properties on page 144 for general instructions about adding connection properties. Example:
<jdbc-type-settings> <type-name>oracle</type-name> <driver>oracle.jdbc.OracleDriver</driver> <connection-urlpattern>jdbc:oracle:thin:@&lt;host&gt;:&lt;port1521&gt;:&lt;sid&gt;</ connection-url-pattern> <ping-command>SELECT 1 FROM DUAL</ping-command> <connection-properties> <connection-property> <key>spotfire.connection.pool.factory.data.source</key> <value>kerberos.data.source</value> </connection-property> <connection-property> <key>oracle.net.authentication_services</key> <value>(KERBEROS5)</value> </connection-property> </connection-properties>

4 5

Use the adddstemplate command (page 177) to add the new data source template with a suitable name, like oracle_kerberos, using the modified template definition. Import the configuration and restart the server as described in the Authentication and User Directory on page 53.

11.4.2.5 Verifying a Data Source Template

1 2 3 4 5 6 7 8 9 10 To verify the data source template from TIBCO Spotfire: Log in to TIBCO Spotfire as an administrator. Select Tools > Create Information Link.... Click on the Setup Data Source link. Enter a name for the data source connection. Specify the type of data source. Enter the connection URL. Enter max/min-values for the connection pool. Enter a username and a password to connect to the database. Note: Does not apply to Kerberos. Click Save. Click on the Data sources tab in the left pane.

TIBCO Spotfire Server 5.5

149 (276)

11 Advanced Procedures

Response: The data source name should appear in the tree to the left, ready for use.

11.5 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 a default join database use the command create-join-db on page 209. Default Join Database Settings
Option Description

Type

Sets the type of database and driver you want to use as the default join database. Refers to a data source template. The connection URL to the database. A minimum and maximum number of connections to use when accessing the database. The Username and Password that will be used to access the database.

Connection URL Number of Connections Username and Password

11.6 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. This example assumes that you are using Microsoft Certificate Services. Note: The exact texts in different dialogs may differ somewhat depending on what version of Microsoft Certificate Services you are using. If in doubt, refer to Microsoft documentation. 1 2 3 On the Spotfire Server, Start Internet Explorer. Connect to your Active Directory Certificate Service homepage. For example, http://<certificate server machine>/certsrv/ Select Request a certificate... > Advanced Request > Submit a certificate request to this CA using a form.

150 (276)

TIBCO Spotfire Server 5.5

11 Advanced Procedures

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. Mark Purpose as Server Authentication Certificate.
Mark Key as Exportable (but do not check Export Key to File). Click Submit and acknowledge that a certificate is being requested. Open the Certification Authority application on the machine where the Certificate Server is installed. Select Certification Authority > Test > Pending requests, where a pending request should be available.

5 6
7 8 9

10

Mark the request, right-click and select All tasks > Issue. Response: The new certificate should now be visible under Issued Certificates. Close the application. Connect to your Active Directory Certificate Service homepage, for example, http://<certificateservermachine>/certsrv/ from the local computer using Internet Explorer. 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.

11 12

13

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. Select Install this certificate > Yes > Yes. Response: A page confirming that the certificate is installed is displayed. In Internet Explorer, select Tools > Internet Options. Select the Content tab. Click the Certificates button. Mark the certificate that was issued to you. Click Export > Next > Yes, export the private key > Next. Check Include all certificates. Comment: There is no need to select Enable strong protection. Select Next. Enter password for the file.
151 (276)

15

16 17 18 19 20 21

22 23

TIBCO Spotfire Server 5.5

11 Advanced Procedures

24

Specify where the key should be saved. Comment: Select Next > Finish.

11.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. Note: The exact texts in different dialogs may differ somewhat depending on what version of Microsoft Certificate Services you are using. If in doubt, refer to Microsoft documentation.

1 2

Request a Certificate: Connect to your Active Directory Certificate Service homepage. For example, http://<certificateservermachine>/certsrv/ using Internet Explorer. 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, for example, not John Doe, but johnd.

1 2 3

Issue the Certificate: Open the Certification Authority application on the machine running the Certificate Services. Select Certification Authority > Test > Pending requests, where a pending request should be available. Mark the request, right-click and select All tasks > Issue. Response: The new certificate should now be visible under Issued Certificates. Close the application.

1 2 3
152 (276)

Install the Certificate: Connect to your Active Directory Certificate Service homepage, for example, http://<certificateservermachine>/certsrv/ from the client computer. Select Check on a pending certificate > Next. Verify that a Client Authentication certificate is selected.
TIBCO Spotfire Server 5.5

11 Advanced Procedures

Click Next. Response: A page with the text Certificate Issued/The certificate you requested was issued to you. is displayed.

5 6

Select Install this certificate. 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 2 3 4 5 6 7 8 9

Open Tools > Internet Options in Internet Explorer. Select the Security tab. Select Local Intranet. Click Sites > Advanced. Add https://<server host name> to the list of hosts in this zone. Click OK. Select Custom level for the Intranet zone security settings. Make sure that Don't prompt for client certificate selection when no certificates or only one certificate exists is Enabled. 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.

TIBCO Spotfire Server 5.5

153 (276)

11 Advanced Procedures

154 (276)

TIBCO Spotfire Server 5.5

Spotfire Server Files

Reference:Spotfire Server Files

This reference describes a select set of files on the Spotfire Server. Some are accessed for information, other for configuration.

SF.1 Server Logs and Diagnostics

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 minimal amount of logging is enabled. For each TIBCO Spotfire Server you can view logs and diagnostics in the Server Logs and Diagnostics tool, available at the URL http://<server>/spotfire:<port>. 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 Deployment and Administration Manual.

Server Logs provide information about what is happening on the server, such as access logs, SOAP communication, Information Links that are used, and so forth. Diagnostics provide information about the server itself, such as information about the Database Server, Operating System, TIBCO Spotfire Server, Application Server, System, and Java version.

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 <installationdir>/tomcat/logs directories. There are several log files that you can configure and view:
Log Name File Name Contents

Configuration Tool Log

tools.log

Information about the activity of the configuration tool. Information about Information Services usage. Information about Spotfire Library usage. Information about Spotfire Library imports and exports. Information about SOAP communication. Information about SQL expressions performed when an information link is executed.

Information Services isusage.log Usage Log Library Log Library Import/ Export Log SOAP Log SQL Log library.log impex.log soap.log sql.log

TIBCO Spotfire Server 5.5

155 (276)

Spotfire Server Files

Server Log

server.log

Information about all activity on the server except those events recorded in the Server Access Log. Information about client access and access attempts to the server and files in the library.

Server Access Log Server Diagnostics Log Server Usage Log Startup Log

access.log

serverdiagnostics.log Diagnostic information about server measures. usage.log startup.log Information about client access and access attempts to the server. Information about JAR files loaded on server startup.

Viewing Logs: To view a log, log in to the Spotfire Administration Console and click Open Logs & Diagnostics, select it from the drop-down list below the text View log file. If the log is very long, it will be paginated. Use the links located above and below the log display to view the entire log. 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 in the drop-down menu below Current Log Configuration, then select the Log Configuration File you want to set for the log, and then click the Set Configuration button. These are the default log configuration files you can choose between by selecting different Log Configuration Files:
Log Configuration File Description

log4jdebugsoap.properties The Server Log logs detailed SOAP information in addition to all the debug information from log4jdebug.properties. Note: Before contacting Spotfire Support, try to collect logs on this log level if you have a Spotfire Server issue. log4jdebugwithconsole properties The Server Log logs detailed debug information as well as warnings, errors and other information. The SQL Log logs detailed SQL information. If the server is started from a command prompt or shell, the output to the command prompt or shell is also included in the Server Log. The Server Log logs detailed debug information as well as warnings, errors and other information. The SQL Log logs detailed SQL information. If the server is started from a command prompt or shell, the output to the command prompt or shell is also included in the Server Log. The Server Log only logs errors, and the SQL Log will be deactivated.

log4jdebug.properties

log4jminimal.properties

156 (276)

TIBCO Spotfire Server 5.5

Spotfire Server Files

log4jtools.properties log4jtracesoap.properties log4jtrace.properties log4j.properties

The log configuration file for the configuration tool. Do not use it for the TIBCO Spotfire Server. The Server Log logs extremely low-level SOAP information including the debug information from log4jtrace.properties. The Server Log logs extremely low-level debug information including the debug information from log4jdebug.properties. The default setting. The Server Log logs warnings, errors and basic information. The SQL Log logs basic SQL information.

Note: Starting with Spotfire Server 3.3, the log configuration set on this page will persist after a Spotfire Server restart. Also Note: Do not use any of the debug configurations for continuous server use as this will impact the performance of the server.

Configuring Logging: If you want to configure logging in other ways than the default configurations, you can create your own Log Configuration File using standard Log4j syntax (refer to http:// logging.apache.org/log4j/1.2/manual.html). This can for instance be used to change when log files are rolled (see above). Placing a new log4j configuration file with the name matching the pattern log4j*.prop erties in the <installationdir>/tomcat/webapps/spotfire/WEBINF directory, will cause it to appear in the drop-down list among the other Log Configuration Files.

Exporting Log Files By clicking on the Export Log File button, you can save the current log file to disk. Logging 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.

SF.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 <installationdir>/tomcat/conf/>. You should only need to make changes to this file 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 file. Therefore, if you need to make changes to it, you need to make those changes to all the servers in the cluster. Note: The variable [SpotfirePort] is set when running the Spotfire Server installer. The variable [ServerHostname]srv is automatically set by the installer by adding the strings srv to the servers hostname. Also note that this variable must not have any characters that need escaping, such as ., for instance spotfireserver1.example.com. For details about the server.xml syntax, refer to Apache Tomcat documentation at http:/ /tomcat.apache.org/
TIBCO Spotfire Server 5.5

157 (276)

Spotfire Server Files

SF.3 bootstrap.xml
The bootstrap configuration file contains the basic information the server needs to bootstrap itself so that it can connect to the Spotfire database and retrieve its configuration. The bootstrap configuration file is created by running the bootstrap command. The file must be created in the<installationdirectory>\tomcat\webapps\spotfire\WEBINF directory (Windows) or the <installationdirectory>/tomcat/webapps/spotfire/WEBINF directory (Unix). When specifying an alternative bootstrap configuration file path to the bootstrap command, the generated file must be manually copied to this directory before it can be used by the server. The file must also be named bootstrap.xml.

To create the bootstrap.xml file: Use the bootstrap command (page 179). The bootstrap configuration file has the format displayed below:
<bootstrap> <server-name>...</server-name> <server> <driver-class>...</driver-class> <database-url>...</database-url> <username>...</username> <password>...</password> </server> <config-tool> <driver-class>...</driver-class> <database-url>...</database-url> <username>...</username> <password>...</password> </config-tool> <server-name>...</server-name> <encryption-password>...</encryption-password> </bootstrap>

The <configtool> section is optional and is not required for running the server itself. It is only required for using the commands to access the database. If the commands are not to be used on a specific server, they can easily be disabled by removing this section. The database password stored in this section is protected by a special configuration tool password that is specified when creating the bootstrap.xml file using the bootstrap command. This tool password must be specified whenever running a command that accesses the database. Please note that the tool password is not related to any administrator user account within the server application itself. The <servername> section contains the server name which is used for identifying the server, for example when specifying server specific configuration. The <encryptionpassword> section is optional. If specified it will contain a password to be used for encrypting other passwords stored in the database. If not set a static password will be used. Note that the same password must be configured for all servers in a cluster.
158 (276)
TIBCO Spotfire Server 5.5

Spotfire Server Files

SF.4 krb5.conf
This file contains settings for Kerberos. The unmodified version of the file is presented first, then a version with example values: Unmodified File
[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

File with Example Values

[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

TIBCO Spotfire Server 5.5

159 (276)

Spotfire Server Files

160 (276)

TIBCO Spotfire Server 5.5

Configuration References

Reference:Configuration References
This reference provides context to the Spotfire Server database connection and parameters for the connection pool. Examples of connection URLs and drivers are also provided.

CR.1 Server Bootstrapping and Database Connection Pool Configuration

The Spotfire database holds all user data and most of the configuration for the Spotfire system. In order to connect to the Spotfire database the Spotfire Server uses a database connection pool. See Database Connectivity on page 161. The bootstrap.xml file contains the information the server needs to connect to the Spotfire database and retrieve the configuration. Refer to bootstrap.xml on page 158. After the server has retrieved the configuration from the database it will re-initialize its database connection pool using information from both the bootstrap.xml file, which is present on each server, and any database configuration set for the entire cluster, stored as part of the database persisted server configuration.

To configure the common database configuration: Use the commands modifydbconfig (page 244) and setdbconfig (page 251). Database Connectivity The Spotfire Server has a database connection pool implementation that is used for two things:

To connect to the Spotfire database To connect to JDBC compliant data sources through Information Services

Each connection pool (either for the Spotfire Server itself or for fetching data) has many parameters, where the following are of general interest:

The driverclass parameter contains the JDBC driver class name. See Database Connection URL Examples on page 163. The url parameter contains the JDBC connection URL. See Database Connection URL Examples on page 163. The username parameter contains the name of the database user to connect as, if applicable. The password parameter contains the password for the specified database user, if applicable. The password is always encrypted and must therefore be set using the bootstrap command (page 179). It cannot be set manually. The minconnections parameter contains the minimum number of allocated connections.
161 (276)

TIBCO Spotfire Server 5.5

Configuration References

The maxconnections parameter contains the maximum number of allocated connections. Depending on the pooling scheme, the total number of connections created by the server may be higher than the value of this parameter during high load, but all such extra connections will automatically be closed when the load decreases. By setting this parameter to zero or a negative value, connection pooling is effectively disabled and new connections will be continuously created, whenever needed. The poolingscheme parameter defines the connection pooling algorithm to be used. There are two possible connection pooling algorithms that determine the way the connection pool operates, DYNAMIC and WAIT. The WAIT algorithm is default. The pooling algorithms are described in detail below.

The DYNAMIC pooling scheme When initialized, the connection pool creates a number of idle database connections equal to the minconnections parameter. When the connection pool receives a request for a database connection, it checks if the pool contains any idle connections and uses one of those, if available. If there are no idle connections in the pool, it automatically creates a new database connection. There is no upper limit for how many connections a connection pool can have open at the same time. Idle connections in the pool eventually time out if they arent used. The connec tiontimeout parameter defines how long time (given in seconds) a connection can stay idle in the connection pool before being closed and discarded. The WAIT pooling scheme When initialized, the connection pool creates a number of idle database connections equal to the minconnections parameter. When the connection pool receives a request for a database connection, it checks if the pool contains any idle connections and uses one of those, if available:

If there are no idle connections in the pool and the number of already open connections is less than the maxconnections parameter, it creates a new database connection. If the number of already open connections is equal to the maxconnections parameter, it waits for an active connection to be returned to the pool. If the request cannot be fulfilled within a number of seconds equal to the logintimeout parameter, the request times out. In the server logs entries like this appear: Timeout while waiting for database connection after 10 seconds.

Thus, in WAIT mode, the connection pool can never have more open (active or idle) connections than the value of the maxconnections parameter. Whenever a database connection is returned, it is put in the pool of idle connections, unless it is used immediately to fulfill an already waiting request. Idle connections in the pool eventually time out if they arent used. The connec tiontimeout parameter defines how long time (given in seconds) a connection can stay idle in the connection pool before being closed and discarded.

162 (276)

TIBCO Spotfire Server 5.5

Configuration References

CR.2 Database Connection URL Examples

This section contains database connection URL examples for connecting to the Spotfire database. Databases and JDBC drivers supported for running the Spotfire Server

Oracle (DataDirect Driver) Driver name: tibcosoftwareinc.jdbc.oracle.OracleDriver

Oracle (Oracle JDBC Thin Driver, ojdbc6.jar) Driver name: oracle.jdbc.OracleDriver

Microsoft SQL Server (DataDirect Driver) Driver name: tibcosoftwareinc.jdbc.sqlserver.SQLServerDriver

Microsoft SQL Server (Microsoft JDBC Driver, sqljdbc4.jar) Driver name: com.microsoft.sqlserver.jdbc.SQLServerDriver

Microsoft SQL Server (jTDS JDBC Driver, jtds.jar) Driver name: net.sourceforge.jtds.jdbc.Driver

Database Connection URL Components

Component Description

API DatabaseDriver

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.

ServerType

Hostname Port DatabaseNameorSID Options

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.

TIBCO Spotfire Server 5.5

163 (276)

Configuration References

Database URL Examples For the different supported database drivers the URL components become: Oracle (DataDirect Driver):
[API]:[DBDriver]:[ServerType]://[Hostname]:[Port];SID=[SID]

Example:
jdbc:tibcospotfireinc:oracle://dbsrv.example.com:1433;SID=spotfire_server

Oracle (Vendor Driver, ojdbc6.jar):

[API]:[DBDriver]:[DriverType]://[Hostname]:[Port]:SID

Example:
jdbc:oracle:thin:@dbsrv.example.com:1521:orcl

Microsoft SQL Server (DataDirect Driver)

[API]:[DBDriver]:[ServerType]://[Hostname]:[Port];DatabaseName=[DBName]

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

Example using Integrated Authentication:

jdbc:tibcosoftwareinc:sqlserver://dbsrv.example.com:1433;DatabaseName= spotfire_server;AuthenticationMethod=ntlm;LoadLibraryPath=c:/tibco/tss/5.5.0/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 (Vendor Driver, sqljdbc4.jar)
[API]:[DBDriver]://[Hostname]:[Port];DatabaseName=[DBName]

Example:
jdbc:sqlserver://dbsrv.example.com:1433;DatabaseName=spotfire_server;selectMethod= cursor

Example: Making sure that the driver always returns will prevent infinite waits during adverse conditions
jdbc:sqlserver://dbsrv.example.com:1433;DatabaseName=spotfire_server;lockTimeout= <X,whereXisagoodvalue>

Note: Due to a restriction in the vendor 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.

164 (276)

TIBCO Spotfire Server 5.5

Configuration References

Example: Using responseBuffering=adaptive:

jdbc:sqlserver://dbsrv.example.com:1433;databaseName=spotfire_server;selectMethod= cursor;responseBuffering=adaptive

Example: Using Integrated Authentication:

jdbc:sqlserver://dbsrv.example.com:1433;DatabaseName=spotfire_server;selectMethod= cursor;integratedSecurity=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 vendor drivers from Microsoft. jTDS (Vendor Driver, jtds.jar):
jdbc:jtds:sqlserver://[Hostname]:[Port]/[DatabaseName]

Example:
jdbc:jtds:sqlserver://dbsrv.example.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.example.com:1433/spotfire_server;instance=FirstInstance

Note: To use other JDBC drivers than the DataDirect ones, you need to install them onto each Spotfire Server. Refer to the section Install Database Drivers on page 27 for more information about this.

TIBCO Spotfire Server 5.5

165 (276)

Configuration References

166 (276)

TIBCO Spotfire Server 5.5

Load Balancing Reference Implementation

Reference:Load Balancing Reference Implementation

Spotfire Server can be deployed to multiple machines, creating a server cluster. This can be used to achieve failover and to balance load between Spotfire Servers. Each Spotfire Server in a cluster communicates with the Same Spotfire database. While it is possible to allow users to connect directly to any of the Spotfire Servers, a more common approach is to use a load balancer. A load balancer is a computer that acts as a front for the Spotfire Servers. The clients connect to the load balancer, which then redirects their communication to an available Spotfire Server. The client has to communicate with the same server during the entire session; that is, sticky sessions or session affinity is maintained. The load balancer must support session affinity and be able to detect if a Spotfire Server becomes available or unavailable. It is possible to use any load balancing technology that supports session affinity. Spotfire Server is implemented using Apache Tomcat, which means that it supports load balancing via AJP (Apache JServ Protocol). This chapter is a reference implementation for a load balancing setup using AJP and a load balancer implementation using Apache HTTP Server with the mod_jk module. The Apache HTTP Server is not supported by TIBCO. If you intend to use a login method that authenticates users with an external directory, this may have implications on how the load balancer should be set up. The procedure is to set up one Spotfire Server to be load balanced. When traffic is being forwarded as it should, others can be added.

LB.1 Prerequisites
Spotfire Server One or more Spotfire Servers installed. It may be a good idea to start with one server and then add more later. Load Balancer A load balancer that supports session affinity. If this is the Apache HTTP Server, it will need:

The mod_jk module installed and enabled. Optional: If NTLM authentication is used, the mod_auth_sspi module installed and enabled.

TIBCO Spotfire Server 5.5

167 (276)

Load Balancing Reference Implementation

LB.2 Spotfire Server Configuration

To enable Spotfire Server to communicate with a load balancer using the AJP protocol the <serverinstallationdirectory>/tomcat/conf/server.xml file has been edited. The following connector section has been uncommented:
<!-- Enable this connector if you want to use a load balancer that supports the Apache JServ Protocol --> <Connector port="8009" protocol="AJP/1.3" packetSize="65536" URIEncoding="UTF-8"/>

Optionally, to prevents clients from connecting to the Spotfire Server directly, forcing them to use the load balancer, HTTP communication can be turned off by commenting out the following connector section:
<Connector port="80" maxHttpHeaderSize="16384" connectionTimeout="30000" enableLookups="false" URIEncoding="UTF-8" disableUploadTimeout="true" server="TIBCO Spotfire Server"/>

LB.3 Load Balancer Configuration

1 2 3 The load balancer has been configured to be able to find and communicate with the Spotfire Servers. Apache httpd has been installed. The mod_jk module has been installed. Refer to the Apache httpd manual for details. The following to workers.properties have been added. 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

168 (276)

TIBCO Spotfire Server 5.5

Load Balancing Reference Implementation

# 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, etc. 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. The following has been added 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

4 5 6 7

It is verified that the Apache httpd configuration includes the file mod_jk.conf. The Apache httpd is restarted and checked for startup errors. It is verified that it is possible to connect to each server using both HTTP on the ports defined in the installation process and using AJP on port 8009. A higher level of security can be achieved by making the load balancer authenticate when it talks to the Spotfire servers. See Setting up HTTPS on page 172 for details.
169 (276)

TIBCO Spotfire Server 5.5

Load Balancing Reference Implementation

LB.4 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 <Servicename="Spotfire">, find the Connector configuration: <Connectorport="8009"protocol="AJP/1.3"packetSize="65536"/> Add the keyword definition:
<Connector port="8009" protocol="AJP/1.3" packetSize="65536" request.useSecret="true" request.secret="SecretKeyword" />

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:
#Enablesecretkeyword 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.

LB.5 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. This is described in this section. To also enable direct login to each server in the cluster without going through the load balancer, the Spotfire Server must also be configured for NTLM. See NTLM Authentication on page 59. Apache HTTPD Configuration 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):
<IfModule !mod_auth_sspi.c> LoadModule sspi_auth_module modules/mod_auth_sspi.so </IfModule> <LocationMatch "/spotfire/(administration|deploy|login|console| support/addsoftware|support/changepassword|support/diagnostics/| support/manuals|ws/LoginService)"> AuthType SSPI 170 (276)

TIBCO Spotfire Server 5.5

Load Balancing Reference Implementation

SSPIAuth On SSPIAuthoritative On SSPIPerRequestAuth On SSPIDomain domain # The name of the authentication realm AuthName "Spotfire 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" </LocationMatch>

LB.6 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, 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, the fully qualified Service Principal Name of the load balancer must be provided.

LB.7 X.509 Client Certificate Authentication

When using X.509 Client Certificate authentication in a clustered environment, the clients see the load balancer as the server, and the load balancer must therefore be provided and configured with a server certificate and its private key. The load balancer also needs to be provided and configured with the CA certificate that was used to issue the server certificate. See the section Setting up HTTPS on page 172 and Configuring X.509 Client Certificates on page 174.
TIBCO Spotfire Server 5.5

171 (276)

Load Balancing Reference Implementation

On the Spotfire Server the Delegate authentication method must be enabled for the load balancer, so that the load balancer can forward the username extracted from the client certificates. See Delegate Authentication Method on page 71.

LB.8 Setting up HTTPS

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 installing 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 2 3 4 5 6 Install Apache httpd with ssl support and the mod_ssl.so and mod_jk modules. Create a self-signed server certificate. If needed, convert the certificate to a format readable by the load balancer. Store the converted certificate in the Apache conf directory. Configure Apache to use the certificate files. 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, continue. Obtain a Certificate You must obtain a certificate to use with the Apache httpd. This can be obtained from a commercial Certificate Authority, or by creating one yourself. Please turn to your provider for information about how to do this. After obtaining this certificate, save it to file and transfer it to the load balancer.

172 (276)

TIBCO Spotfire Server 5.5

Load Balancing Reference Implementation

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 <apachehttpddir>/conf. Configure Apache httpd to Use the Certificate Files Add the following lines to the Apache httpd configuration (for instance, to the load balancers 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 If you have obtained a CA Certificate from a commercial CA, your clients probably already trust it. If you have created it yourself, please refer to your CA software documentation on how to get clients to trust it.

TIBCO Spotfire Server 5.5

173 (276)

Load Balancing Reference Implementation

LB.9 Configuring X.509 Client Certificates

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 2 3 4 Configure the Spotfire system to use X.509 Client Certificate authentication. See Authentication using X.509 Client Certificates on page 70. Configure Apache httpd to communicate using the HTTPS protocol. See the section Setting up HTTPS on page 172. Configure Apache httpd to require and forward X.509 client certificates. 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 balancers 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)
JkEnvVarSSL_CLIENT_CERT

You should now have a load balancer that requires and forwards X.509 Client Certificates.

LB.10Shared Disk Location

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.

174 (276)

TIBCO Spotfire Server 5.5

Load Balancing Reference Implementation

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. 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/LibraryImportExportService loadbalancer JkUnmount /spotfire/ws/LibraryImportExportService/* loadbalancer JkMount /spotfire/ws/LibraryImportExportService worker1 JkMount /spotfire/ws/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.

TIBCO Spotfire Server 5.5

175 (276)

Load Balancing Reference Implementation

176 (276)

TIBCO Spotfire Server 5.5

Reference:Commands
Commands are listed alphabetically. Refer to Available Configuration Commands on page 44 for an easily reviewed functional command grouping and Authentication and User Directory on page 53 for the procedure to configure using commands. Synopsis: Angle brackets (<>) indicate mandatory arguments, Square brackets ([]) indicate optional arguments. Arguments can normally be specified in two different formats. For example, the maxcachesize argument as: maxcachesize=<value> or m<value>. Note: A negative value must be preceded by a backslash in the later mentioned argument format. For example m\7.

add-ds-template
Adds a new data source template. SYNOPSIS
add-ds-template [-c value | --configuration=value] [-b value | --bootstrap-config=value] <-n value | --name=value> [-e <true|false> | --enabled=<true|false>] <template definition file>

OVERVIEW This command is used to add a new data source template used by Information Services. The name of the template must be unique. OPTIONS
-c value --configuration=value

The path to the server configuration file. This argument is optional. The default value is configuration.xml.
-b value --bootstrap-config=value

The path to the bootstrap configuration file. Refer to bootstrap.xml on page 158. This argument is optional.
-n value --name=value

The name of the data source template to add. This argument is mandatory.
-e <true|false> --enabled=<true|false>

The enable flag indicates whether or not the newly created data source template should be enabled. This argument is optional. The default value is false.
<template definition file>

The path to the file containing the data source template definition. This argument is mandatory.
TIBCO Spotfire Server 5.5 177 (276)

add-member
Adds a user or group as a member of a specified group. SYNOPSIS
add-member [-b value | --bootstrap-config=value] [-t value | --tool-password=value] <-g value | --groupname=value> [-u value | --member-username=value] [-m value | --member-groupname=value]

OVERVIEW This command is used to add an existing user or group as a member of another existing group. OPTIONS The arguments are as follows:
-b value --bootstrap-config=value

The path to the bootstrap configuration file. See the 'bootstrap.xml' help topic for more information about this file. This argument is optional.
-t value --tool-password=value

The configuration tool password used to decrypt the database password in the bootstrap.xml file. If the tool password is omitted, the command will prompt the end-user for it on the console. See the 'bootstrap.xml' help topic for more information. This argument is optional.
-g value --groupname=value

The name of the group to which the member should be added. Unless the group is part of the internal SPOTFIRE domain, the name of the group must include the group's domain name, for example RESEARCH\group or [email protected] . This argument is mandatory.
-u value --member-username=value

The name of the user to add as a member of the specified group. Unless the user is part of the configured default domain, the name of the user must include the user's domain name, for example RESEARCH\user or [email protected]. The memberuser name and membergroupname arguments are mutually exclusive. This argument is mandatory, unless the membergroupname argument is specified.
-m value --member-groupname=value

The name of the group to add as a member of the specified group. Unless the group is part of the internal SPOTFIRE domain, the name of the group must include the group's domain name, for example RESEARCH\group or [email protected]. The memberusername and membergroupname arguments are mutually exclusive. This argument is mandatory, unless the memberusername argument is specified.

178 (276)

TIBCO Spotfire Server 5.5

bootstrap
Bootstraps the server by creating a new bootstrap.xml file containing the information needed to connect to the database. SYNOPSIS
bootstrap [-f | --force] [-T | --test] [-n | --no-prompt] [-c value | --driver-class=value] [-d value | --database-url=value] [-u value | --username=value] [-p value | --password=value] [-k value | --kerberos-login-context=value] {-Ckey=value} [-E <true|false> | --enable-config-tool=<true|false>] [-t value | --tool-password=value] [-e value | --encryption-password=value] [-s value | --server-name= value] [bootstrap configuration file]

OVERVIEW This command is used to create a new bootstrap configuration file. OPTIONS
-f --force

When this flag is specified, the tool will overwrite any already existing bootstrap configuration file. This argument is optional.
-T --test

When this flag is specified, the tool will test the created configuration by attempting to connect to the database using the specified connection information. This argument is optional.
-n --no-prompt

When this flag is specified, the tool will not prompt for any missing password arguments. This argument is optional.
-c value --driver-class=value

This argument specifies the name of the JDBC driver class. This argument is optional. The default value is: tibcosoftwareinc.jdbc.oracle.OracleDriver.
-d value --database-url=value

This argument specifies the JDBC URL to the database. Since this argument usually contains special characters, make sure to escape those characters or enclose the values between quotes. This argument is optional. The default value is:
jdbc:tibcosoftwareinc:oracle://localhost:1521;SID=orcl
-u value --username=value

This argument specifies the database accounts username. This argument is optional.

TIBCO Spotfire Server 5.5

179 (276)

-p value --password=value

This argument specifies the database accounts password. This argument is optional.
-k value --kerberos-login-context=value

This argument specifies the name of the JAAS application configuration to be used for acquiring the Kerberos TGT, when using the Kerberos protocol to login to the database. This JAAS application configuration must be registered with Java using a login.config.url parameter in the <TSS installation directory>\jdk\jre\lib\security\ java.security (Windows) or <TSSinstallation directory>/jdk/jre/lib/security/java.security (Unix) file. The Spotfire Server importjaasconfig command cannot be used for this purpose, since the JAAS application configurations that are imported using this command will be stored in the database itself, which prevents the Spotfire Server from using them for creating the initial connection to the database. This argument is optional.
-Ckey=value

A JDBC connection property. Several properties may be specified. This argument is optional and may be specified multiple times with different keys.
-E <true|false> --enable-config-tool=<true|false>

This argument specifies whether the <config-tool> section should be created or not. Without this section, the configuration tool cannot be used on this computer. See the bootstrap.xml help topic for more information. This argument is optional. The default value is true.
-t value --tool-password=value

The configuration tool password used to decrypt the database password in the file bootstrap.xml . Can be specified if and only if a password is given and the flag enableconfigtool is set to true (the default). This argument is optional.
-e value --encryption-password=value

This argument may be used for specifying a password to be used for encrypting passwords stored in the database. If not set a static password will be used. Note that the same password must be configured for all servers in a cluster. This argument is optional.
-s value --server-name=value

This argument specifies the server name. Used for identifying the server, for example when specifying server specific configuration. The default value is the fully qualified host name as determined when this command is run. This argument is optional.
[bootstrap configuration file]

This argument specifies the path to the bootstrap configuration file to create. Refer to bootstrap.xml on page 158. This argument is optional.

180 (276)

TIBCO Spotfire Server 5.5

EXAMPLES Bootstrap the server to use an Oracle database with the bundled DataDirect JDBC driver:
bootstrap driverclass=tibcosoftwareinc.jdbc.oracle.OracleDriver databaseurl= "jdbc:tibcosoftwareinc:oracle://server:1521;SID=spotfire" username=spotuser password=spotuser

Bootstrap the server to use an Oracle database with Oracles thin JDBC driver:
bootstrap driverclass=oracle.jdbc.OracleDriver databaseurl="jdbc:oracle:thin:@ server:1521:spotfire" username=spotuser password=spotuser

Bootstrap the server to use a Microsoft SQL Server database with the bundled DataDirect JDBC driver:
bootstrapdriverclass=tibcosoftwareinc.jdbc.sqlserver.SQLServerDriverdatabaseurl= "jdbc:tibcosoftwareinc:sqlserver://server:1433;DatabaseName=spotfire_server" username=spotuserpassword=spotuser

Bootstrap the server to use a Microsoft SQL Server database with Microsofts JDBC driver:
bootstrapdriverclass=com.microsoft.sqlserver.jdbc.SQLServerDriverdatabaseurl= "jdbc:sqlserver://server:1433;DatabaseName=spotfire_server"username=spotuser password=spotuser

Bootstrap the server to use a Microsoft SQL Server database with the jTDS JDBC driver:
bootstrap driverclass=net.sourceforge.jtds.jdbc.Driver databaseurl= "jdbc:jtds:sqlserver://server:1433/spotfire_server" username=spotuser password= spotuser

clear-join-db
Clears the default join database configuration. SYNOPSIS
clear-join-db [-c value | --configuration=value] [-b value | --bootstrap-config=value]

OVERVIEW This command is used to clear the default join database configuration, which means that the Spotfire database will be used as default join database, the default behavior. OPTIONS
-c value --configuration=value

The path to the server configuration file. This argument is optional. The default value is configuration.xml.

TIBCO Spotfire Server 5.5

181 (276)

-b value --bootstrap-config=value

The path to the bootstrap configuration file. Refer to bootstrap.xml on page 158. This argument is optional.

config-action-log-database-logger
Configures the user action database logger. SYNOPSIS
config-action-log-database-logger [-c value | --configuration=value] [-b value | --bootstrap-config=value] [--driver-class=value] [-d value | --database-url=value] [-u value | --username=value] [-p value | --password=value] [--commit-period=value] [--wait-on-full-queue-time=value] [--wait-on-empty-queue-time=value] [--grace-period=value] [--pruning-period=value] [--queue-size=value] [--batch-size=value] [--thread-pool-size=value] [--workers=value] [--block-on-full-queue=<true|false>]

OVERVIEW This command configures the user action database logger. OPTIONS The arguments are as follows:
-c value --configuration=value

The path to the server configuration file. This argument is optional. The default value is configuration.xml.
-b value --bootstrap-config=value

The path to the bootstrap configuration file. See the bootstrap.xml help topic for more information about this file. This argument is optional.
--driver-class=value

This argument specifies the name of the JDBC driver class. This argument is optional.
-d value --database-url=value

This argument specifies the JDBC URL to the database. Since this argument usually contains special characters, make sure to escape those characters or enclose the values between quotes. This argument is optional.
-u value --username=value

This argument specifies the database account's username. This argument is optional.
-p value --password=value

This argument specifies the database account's password. This argument is optional.

182 (276)

TIBCO Spotfire Server 5.5

--commit-period=value

Sets how often (in seconds) log events should be committed from the queue to the database when the queue is not full. This argument is optional.
--wait-on-full-queue-time=value

Sets the time (in milliseconds) to wait before retrying to place a new log event on the queue after being rejected by a full queue. This argument is optional.
--wait-on-empty-queue-time=value

Sets the time (in milliseconds)to wait before trying to create a batch from the queue after an empty queue has been encountered. This argument is optional.
--grace-period=value

Sets the grace period for the database logger (in seconds). This is the period that the database logger is given at server shutdown to move all items from the queue to the database. This argument is optional.
--pruning-period=value

Sets the maximum time (in hours) that logged items are kept in the database. Pruning will take place at server startup and then at one hour intervals, when all items older than the here specified number of hours will be deleted. To disable pruning, set this argument to 0. This argument is optional.
--queue-size=value

Sets the maximum number of log events in the queue. This argument is optional.
--batch-size=value

Sets the number of log events that should be moved from the queue to the database in each batch insert. This argument is optional.
--thread-pool-size=value

Sets the number of threads available for the batch insert workers. This argument is optional.
--workers=value

Sets the maximum number of batch insert workers at any given time. This argument is optional.
--block-on-full-queue=<true|false>

Sets whether or not placing a log event on the queue should be allowed to be blocked indefinitely if the queue is full. This argument is optional.

config-action-log-web-service
Configures the action log web service. SYNOPSIS
config-action-log-web-service [-c value | --configuration=value] [-b value | --bootstrap-config=value] [--categories=value] [--allowedHosts=value]

OVERVIEW This command configures the user action log web service.

TIBCO Spotfire Server 5.5

183 (276)

OPTIONS The arguments are as follows:

-c value --configuration=value

The path to the server configuration file. This argument is optional. The default value is configuration.xml.
-b value --bootstrap-config=value

The path to the bootstrap configuration file. See the bootstrap.xml help topic for more information about this file. This argument is optional.
--categories=value

A comma separated list of categories that should be allowed to log through the web service. To enable all categories, please specify 'all'. This argument is optional.
--allowedHosts=value

A regular expression that sets the hosts allowed to use the logger web service. To enable all hosts, please specify '.*'. This argument is optional.

config-action-logger
Configures the user action logger. SYNOPSIS
config-action-logger [-c value | --configuration=value] [-b value | --bootstrap-config=value] [--categories=value] [--file-logging-enabled=<true|false>] [--database-logging-enabled= <true|false>]

OVERVIEW This command configures the user action logger. OPTIONS The arguments are as follows:
-c value --configuration=value

The path to the server configuration file. This argument is optional. The default value is configuration.xml.
-b value --bootstrap-config=value

The path to the bootstrap configuration file. See the 'bootstrap.xml' help topic for more information about this file. This argument is optional.
--categories=value

A comma separated list of the categories that should be logged by the user action logger. To enable logging for all categories, please specify 'all'. This argument is optional.
--file-logging-enabled=<true|false>

Sets whether or not the user action logger should log to file. This argument is optional.
184 (276) TIBCO Spotfire Server 5.5

--database-logging-enabled=<true|false>

Sets whether or not the user action logger should log to database. This argument is optional.

config-attachment-manager
Configures the Attachment Manager. SYNOPSIS
config-attachment-manager [-c value | --configuration=value] [-b value | --bootstrap-config=value] [-e value | --max-cache-expiration-time= value] [-m value | --max-cache-size=value] [-E <true|false> | --encryption-enabled=<true|false>] [-k value | --encryption-key-size= value]

OVERVIEW This command is used to configure the Attachment Manager which handles data transfer to and from the TIBCO Spotfire Server (for instance Library downloads and uploads). OPTIONS The arguments are as follows:
c value --configuration=value

The path to the server configuration file. This argument is optional. The default value is configuration.xml.
-b value --bootstrap-config=value

The path to the bootstrap configuration file. See the bootstrap.xml help topic for more information about this file. This argument is optional.
-e value --max-cache-expiration-time=value

Controls the maximum idle time (in seconds) after which cache entries will be evicted. Setting this parameter to a negative value will disable the cache. This argument is optional. The default value is 86400.
-m value --max-cache-size=value

Controls the maximum amount of disk space (in megabytes) used by the cache. Setting this parameter to a negative value will disable the cache. This argument is optional. The default value is 10240.
-E <true|false> --encryption-enabled=<true|false>

Controls whether the encryption of temp files should be enabled or not. This argument is optional. The default value is true.

TIBCO Spotfire Server 5.5

185 (276)

-k value --encryption-key-size=value

Controls the size of the encryption key used when encrypting temp files. This argument is optional. The default value is 128.

config-auth
Configures authentication mode and default domain. SYNOPSIS
config-auth [-c value | --configuration=value] [-b value | --bootstrap-config=value] [-a value | --auth-method=value] [-d | --jaas-database] [-l | --jaas-ldap] [-w | --jaas-windows] [-j value | --jaas-custom=value] [-D value | --default-domain=value] [-p <true| false> | --parse-user-and-domain-name=<true|false>]

OVERVIEW This command is used to configure the authentication mode and to set the default domain. OPTIONS The arguments are as follows:
-c value --configuration=value

The path to the server configuration file. This argument is optional. The default value is configuration.xml.
-b value --bootstrap-config=value

The path to the bootstrap configuration file. See the bootstrap.xml help topic for more information about this file. This argument is optional.
-a value --auth-method=value

The authentication method to use. The following methods are supported: BASIC, CLIENT_CERT, NTLM, Kerberos and Delegate. The names may be specified in either upper or lower case. This argument is optional.
-d --jaas-database

Use the Spotfire database authentication source, as configured in the Spotfire-DBLogin JAAS application configuration. This option is only permitted when using the BASIC authentication method. It is also mutually exclusive with all other options related to BASIC authentication sources. This argument is optional.
-l --jaas-ldap

Use the LDAP authentication source, as configured in the SpotfireLDAP JAAS application configuration. This option is only permitted when using the BASIC authentica-

186 (276)

TIBCO Spotfire Server 5.5

tion method. It is also mutually exclusive with all other options related to BASIC authentication sources. This argument is optional.
-w --jaas-windows

Use the Windows NT authentication source, as configured in the SpotfireWindows JAAS application configuration. This option is only permitted when using the BASIC authentication method. It is also mutually exclusive with all other options related to BASIC authentication sources. This argument is optional.
-j value --jaas-custom=value

Use the custom JAAS application configuration with the specified name. This option is only permitted when using the BASIC authentication method. It is also mutually exclusive with all other options related to BASIC authentication sources. This argument is optional.
-D value --default-domain=value

The name of the default domain. Users belonging to the default domain do not have to specify domain name as part of their username when logging in to the server. The default value is SPOTFIRE, which is the name of the domain used when running the User Directory in database mode. This argument is optional.
-p <true|false> --parse-user-and-domain-name=<true|false>

Indicates whether or not the username consists of both a user and a domain part that should be parsed. It is recommended to avoid changing the default value of true, except for when running the User Directory in database mode and the usernames are in either NetBIOS name format (domain\user) or email name format (user@domain). This argument is optional.

config-basic-database-auth
Configures the Spotfire Database authentication source for use with the BASIC authentication method. SYNOPSIS
config-basic-database-auth [-c value | --configuration=value] [-b value | --bootstrap-config=value] [-p <true|false> | --parse-user-and-domain-name=<true|false>]

OVERVIEW This command is used to configure the Spotfire Database authentication source for use with the BASIC authentication method. The configuration is stored within the SpotfireDatabase JAAS application configuration. OPTIONS The arguments are as follows:

TIBCO Spotfire Server 5.5

187 (276)

-c value --configuration=value

The path to the server configuration file. This argument is optional. The default value is 'configuration.xml'.
-b value --bootstrap-config=value

The path to the bootstrap configuration file. See the 'bootstrap.xml' help topic for more information about this file. This argument is optional.
-p <true|false> --parse-user-and-domain-name=<true|false>

This argument is deprecated and will be ignored. Please use the config-auth command to set the global configuration property instead. This argument is optional.

config-basic-ldap-auth
Configures the LDAP authentication source for use with the BASIC authentication method. SYNOPSIS
config-basic-ldap-auth [-c value | --configuration=value] [-b value | --bootstrap-config=value] [-l value | --ldap-configs=value] [-w <true|false> | --enable-wildcard-domain=<true|false>]

OVERVIEW This command is used to configure the LDAP authentication source for use with the BASIC authentication method. The configuration is stored within the SpotfireLDAP JAAS application configuration. OPTIONS
-c value --configuration=value

The path to the server configuration file. This argument is optional. The default value is configuration.xml.
-b value --bootstrap-config=value

The path to the bootstrap configuration file. Refer to bootstrap.xml on page 158. This argument is optional.
-l value --ldap-configs=value

A comma-separated list of LDAP configuration references. All referenced LDAP configurations must already exist. To create a new LDAP configuration, use the cre ateldapconfig command. When specifying more than one reference, make sure to enclose the list of references in double quotes. This argument is optional.

188 (276)

TIBCO Spotfire Server 5.5

-w <true|false> --enable-wildcard-domain=<true|false>

Indicates whether or not the server should attempt to authenticate the user in all domains until an authentication attempt succeeds whenever the end-user omits the domain name in the account name credential. This argument is optional.

config-basic-windows-auth
Configures the Windows NT authentication source for use with the BASIC authentication method. SYNOPSIS
config-basic-windows-auth [-c value | --configuration=value] [-b value | --bootstrap-config=value] [-d value | --domains=value] [-w <true| false> | --enable-wildcard-domain=<true|false>]

OVERVIEW This command is used to configure the Windows NT authentication source for use with the BASIC authentication method. The configuration is stored within the SpotfireWindows JAAS application configuration. OPTIONS
-c value --configuration=value

The path to the server configuration file. This argument is optional. The default value is configuration.xml.
-b value --bootstrap-config=value

The path to the bootstrap configuration file. Refer to bootstrap.xml on page 158. This argument is optional.
-d value --domains=value

A comma-separated list of domain names. When specifying more than one domain name, make sure to enclose the list of names in quotes. This argument is optional.
-w <true|false> --enable-wildcard-domain=<true|false>

Indicates whether or not the server should attempt to authenticate the user in all domains until an authentication attempt succeeds whenever the end-user omits the domain name in the account name credential. This argument is optional.

config-client-cert-auth
Configures the CLIENT_CERT authentication method.

TIBCO Spotfire Server 5.5

189 (276)

SYNOPSIS
config-client-cert-auth [-c value | --configuration=value] [-b value | --bootstrap-config=value] <-n value | --name-attribute=value> [-d <true|false> | --name-attribute-contains-domain=<true|false>]

OVERVIEW This command is used to configure the X.509 certificate name attribute used for the CLIENT_CERT authentication method. OPTIONS
-c value --configuration=value

The path to the server configuration file. This argument is optional. The default value is configuration.xml.
-b value --bootstrap-config=value

The path to the bootstrap configuration file. Refer to bootstrap.xml on page 158. This argument is optional.
-n value --name-attribute=value

The name of the attribute that should be used to extract usernames from X.509 certificates. Supported attributes are any attribute that can occur in the certificate subjects distinguished name (for instance "CN"), "DN" (use the whole distinguished name), or any subject alternative name of type "rfc822Name", "dNSName", "directoryName", "uniformResourceIdentifier", "iPAddress" or "registeredID". To use a subject alternative name, the name attribute must have the prefix "subjectAltName:". If more than one subject alternative name are present in the certificates, an index can be added prefixed with a pound sign (#). This argument is mandatory.
d <true|false> --name-attribute-contains-domain=<true|false>

Indicates whether or not the specified name attribute contains a fully qualified account name, with both a username part and a domain name part. This argument is optional. The default value is false.

config-delegate-auth
Configures the Delegate authentication method. SYNOPSIS
config-delegate-auth [-c value | --configuration=value] [-b value | --bootstrap-config=value] [-e <true|false> | --enabled=<true|false>] [-a value | --request-attribute=value] [-x value | --expression= value] [-d <true|false> | --downcase=<true|false>] [-h value | --allowed-hosts=value]

190 (276)

TIBCO Spotfire Server 5.5

OVERVIEW This command is used to configure the Delegate authentication method. The authentication method can either be used as the main authentication method, as configured by the setauthmode command, or as a complementary authentication method where it is combined with the main method.

It is typically used as the main method when the clients only can access the server(s) through a proxy or a load-balancer. To use it as the main authentication method, first configure and enable the method using this command and then set it to the main method using the setauthmode command. It is typically used as a complementary method when the clients can access the server(s) both directly and through a proxy or a load-balancer. To use it as a complementary method, simply configure and enable the method using this command.

OPTIONS
-c value --configuration=value

The path to the server configuration file. This argument is optional. The default value is configuration.xml.
-b value --bootstrap-config=value

The path to the bootstrap configuration file. Refer to bootstrap.xml on page 158. This argument is optional.
-e <true|false> --enabled=<true|false>

Specifies whether or not the Delegate authentication method should be enabled. This argument is optional. The default value is true.
-a value --request-attribute=value

The name of the HTTP request attribute containing the name of the authenticated user. This argument is optional. The default value is REMOTE_USER.
-x value --expression=value

A regular expression that can be used to filter the username extracted from the specified HTTP request attribute. The value of the regular expressions first capturing group will be used as the new username. A typical scenario is to extract the username from a composite name containing both username and domain name. For instance, the regular expression \S\\(\S*) can be used to extract the username from a value in the format domain\username. Please make sure to enclose the specified expression in quotes and to quote all special characters that might otherwise be consumed by the command line shell. This argument is optional.
-d <true|false> --downcase=<true|false>

Specifies whether or not the username should be converted to lowercase. This argument is optional. The default value is false.

TIBCO Spotfire Server 5.5

191 (276)

-h value --allowed-hosts=value

A comma-separated list of hostnames and/or IP addresses of the client computers that are permitted to login already authenticated users by passing the usernames in the specified HTTP request attribute. If this argument is not specified, then all client computers are permitted to perform delegated authentication. As this is a potential security risk, it is strongly recommended to restrict the permissions to use this feature. Typically, this feature is locked down so that only proxies or load-balancers are permitted to use it. A scenario where all client computers can be allowed to use this feature is when a custom Post Authentication Filter is also in use. Then this filter would be responsible for performing the final authorization, for instance by validating additional HTTP headers. This argument is optional.

config-impersonation-auth
Configures the Impersonation authentication method. SYNOPSIS
config-impersonation-auth [-c value | --configuration=value] [-b value | --bootstrap-config=value] [-e <true|false> | --enabled=<true| false>] [-s <true|false> | --require-ssl=<true|false>] [-p <true| false> | --use-post-auth-filter=<true|false>] [-u value | --allowed-users=value] [-h value | --allowed-hosts=value]

OVERVIEW This command is used to configure the Impersonation authentication method. This is a complementary authentication method which allows super-users, known as impersonators, to assume the identity of a specified user. This feature is typically used by the TIBCO Spotfire Web Player. OPTIONS
-c value --configuration=value

The path to the server configuration file. This argument is optional. The default value is configuration.xml.
-b value --bootstrap-config=value

The path to the bootstrap configuration file. Refer to bootstrap.xml on page 158. This argument is optional.
-e <true|false> --enabled=<true|false>

Specifies whether or not the Impersonation authentication method should be enabled. This argument is optional. The default value is true.

192 (276)

TIBCO Spotfire Server 5.5

-s <true|false> --require-ssl=<true|false>

Specifies whether or not a secure HTTPS connection is required for using the Impersonation feature. This argument is optional. The default value is false.
-p <true|false> --use-post-auth-filter=<true|false>

Specifies whether or not the Impersonation feature should apply the configured Post Authentication Filter after switching the identity. This argument is optional. The default value is true.
-u value --allowed-users=value

This argument is deprecated and will be ignored. Please add the users to the Imperson atorgroup instead. This argument is optional.
-h value --allowed-hosts=value

A comma-separated list of hostnames and/or IP addresses of the client computers that are permitted to use the Impersonation feature. If this argument is not specified, then all client computers are permitted to use the feature. As this is a potential security risk, it is strongly recommended to restrict the permissions to use it. Typically, this feature is locked down so that only the computers running the TIBCO Spotfire Web Player are permitted to use it. This argument is optional.

config-import-export-directory
Configures the library import/export directory. SYNOPSIS
config-import-export-directory [-c value | --configuration=value] [-b value | --bootstrap-config=value] [-p value | --path=value]

OVERVIEW This command is used to configure the library import/export directory. All library import and export operations will be done from/to this directory which may be a local directory of reside on a shared disk. OPTIONS
-c value --configuration=value

The path to the server configuration file. This argument is optional. The default value is configuration.xml.
-b value --bootstrap-config=value

The path to the bootstrap configuration file. Refer to bootstrap.xml on page 158. This argument is optional.

TIBCO Spotfire Server 5.5

193 (276)

-p value --path=value

The path to the import/export directory. This argument is optional. The default value is <installationdirectory>/tomcat/applicationdata/library.

config-jmx
Configures the JMX RMI connector. SYNOPSIS
config-jmx [-c value | --configuration=value] [-b value | --bootstrap-config=value] [-e <true|false> | --enabled=<true|false>] [-a <true|false> | --authentication-enabled=<true|false>] [-A <true| false> | --authorization-enabled=<true|false>] [-s <true|false> | --ssl-enabled=<true|false>] [-r <true|false> | --registry-ssl-enabled=<true|false>] [-n <true|false> | --need-client-auth=<true|false>] [-R value | --registry-port=value] [-p value | --connector-port=value] [-j value | --jaas-config=value]

OVERVIEW This command is used to configure the JMX RMI connector which may be used for connecting to the TIBCO Spotfire Server for monitoring and management purposes. OPTIONS
-c value --configuration=value

The path to the server configuration file. This argument is optional. The default value is configuration.xml.
-b value --bootstrap-config=value

The path to the bootstrap configuration file. Refer to bootstrap.xml on page 158. This argument is optional.
-e <true|false> --enabled=<true|false>

Controls whether the RMI connector is enabled or not. This argument is optional. The default value is false.
-a <true|false> --authentication-enabled=<true|false>

Controls whether authentication is enabled for the RMI connector or not. This argument is optional. The default value is true.
-A <true|false> --authorization-enabled=<true|false>

Controls whether authorization is enabled for the RMI connector or not. Authorization requires authentication to be enabled and only works with the default value of jaasconfig. This argument is optional. The default value is true.

194 (276)

TIBCO Spotfire Server 5.5

-s <true|false> --ssl-enabled=<true|false>

Controls whether SSL is enabled for the RMI connector or not. This argument is optional. The default value is false.
-r <true|false> --registry-ssl-enabled=<true|false>

Controls whether SSL is enabled for the RMI registry or not. This argument is optional. The default value is false.
-n <true|false> --need-client-auth=<true|false>

Controls whether SSL client authentication is required or not. This argument is optional. The default value is false.
-R value --registry-port=value

The port for the RMI registry. This argument is optional. The default value is 1099.
-p value --connector-port=value

The port for the RMI connector. This argument is optional. The default value is 1099.
-j value --jaas-config=value

The JAAS configuration entry to use for authentication. Requires authentication to be enabled. User accounts for the default authentication implementation are created by the createjmxuser command. This argument is optional. The default value is SpotfireJmx.

config-kerberos-auth
Configures the authentication service used with the Kerberos authentication method. SYNOPSIS
config-kerberos-auth [-c value | --configuration=value] [-b value | --bootstrap-config=value] <-p value | --service-principal-name=value> [-k value | --keytab-file=value] [-d <true|false> | --enable-debug= <true|false>]

OVERVIEW This command is used to configure the authentication service used with Kerberos authentication method. OPTIONS
-c value --configuration=value

The path to the server configuration file. This argument is optional. The default value is configuration.xml.

TIBCO Spotfire Server 5.5

195 (276)

-b value --bootstrap-config=value

The path to the bootstrap configuration file. Refer to bootstrap.xml on page 158. This argument is optional.
-p value --service-principal-name=value

The Kerberos service principal name (SPN) used by the server. This argument is mandatory.
-k value --keytab-file=value

The path to the Kerberos file containing the keytab entry for the specified SPN. If the specified path contains any Java system properties (for example as in the default value for this argument), they will automatically be expanded. This argument is optional. The default value is ${java.home}/lib/security/spotfire.keytab.
-d <true|false> --enable-debug=<true|false>

Decides whether extra debug logging should be enabled or disabled for the Kerberos authentication service. This argument is optional. The default value is false.

config-ldap-group-sync
Configures group synchronization for an LDAP configuration. SYNOPSIS
config-ldap-group-sync [-c value | --configuration=value] [-b value | --bootstrap-config=value] <--id=value> [--group-sync-enabled=<true| false>] [--schedules=value] [--clear-schedules] [--group-names=value] [--clear-group-names] [--clear-all] [--group-search-filter=value] [--group-name-attribute=value] [--supports-member-of=<true|false>] [--member-attribute=value] [--ignore-member-groups=<true|false>]

OVERVIEW This command is used to configure group synchronization for an LDAP configuration used with the User Directory LDAP provider. OPTIONS
-c value --configuration=value

The path to the server configuration file. This argument is optional. The default value is configuration.xml.
-b value --bootstrap-config=value

The path to the bootstrap configuration file. Refer to bootstrap.xml on page 158. This argument is optional.

196 (276)

TIBCO Spotfire Server 5.5

--id=value

Specifies the identifier of the LDAP configuration to configure group synchronization for. This argument is mandatory.
--group-sync-enabled=<true|false>

Specifies whether or not group synchronization should be enabled for this LDAP configuration. This argument is optional. The default value is true.
--schedules=value

Note: This argument is deprecated from 5.0 and is replaced with the similarly named argument for the create-ldap-config on page 210 and update-ldap-config on page 261 commands, because the synchronization schedules are now used for both user and group synchronization. The argument specifies a comma-separated list of schedules for when the LDAP synchronization should be performed. The schedules are given in a cron-compatible format, where each schedule consists of either five fields or one shorthand label. This argument is optional. The five fields are, from left to right, with their valid ranges: minute (0-59), hour (0-23), day of month (1-31), month (1-12) and day of week (0-7, where both 0 and 7 indicate Sunday). A field may also be configured with the wildcard character *, indicating that any moment in time matches this field. A group synchronization is triggered when all fields match the current time. If both day of month and day of week have non-wildcard values, then only one of them has to match. There are also the following shorthand labels that can be used instead of the full cron expressions:
@yearlyor@annually:runonceayear(equivalentto0011*) @monthly:runonceamonth(equivalentto001**) @weekly:runonceaweek(equivalentto00**0) @dailyor@midnight:runonceaday(equivalentto00***) @hourly:runonceanhour(equivalentto0****) @minutely:runonceaminute(equivalentto*****) @rebootor@restart:runeverytimetheSpotfireServerisstarted

Refer to the Wikipedia overview article on the cron scheduler.

--clear-schedules

Note: This argument is deprecated from 5.0 and is replaced with the similarly named argument for the update-ldap-config on page 261 command, because the synchronization schedules are now used for both user and group synchronization. By specifying this flag, the LDAP synchronization schedules are cleared from the LDAP configuration. This flag can be used together with the schedules flag to remove all old schedules before adding the new. This argument is optional.
--group-names=value

Specifies the account names or the distinguished names (DNs) of the groups to be synchronized. This argument is optional.

TIBCO Spotfire Server 5.5

197 (276)

--clear-group-names

By specifying this flag, the list of group names to be synchronized are cleared from the LDAP configuration. This flag can be used together with the groupnames flag to remove all old group names before adding the new. This argument is optional.
--clear-all

By specifying this flag, all group synchronization related configuration options are cleared from the LDAP configuration. Note: Starting from TIBCO Spotfire Server 5.0, it will NOT clear the LDAP synchronization schedules. This argument is optional.
--group-search-filter=value

This parameter specifies an LDAP search expression filter to be used when searching for groups. For Active Directory servers, the parameter value defaults to objectClass=group. For Sun ONE Directory Servers, it defaults to &(|(objectclass=
nsManagedRoleDefinition)(objectClass=nsNestedRoleDefinition))(objectclass= ldapSubEntry). For Sun Java System Directory Servers, it defaults to objectClass= groupOfUniqueNames. Unless the LDAP server type is set to Custom using the type parameter, this argument

is optional.
--group-name-attribute=value

Specifies the name of the LDAP attribute containing the group account names: For Active Directory servers the value defaults to sAMAccountName. For any version of the Sun directory servers with a default configuration, it defaults to cn. Unless the LDAP server type is set to Custom using the type parameter, this argument is optional.
--supports-member-of=<true|false>

Specifies whether or not the LDAP servers support a memberOf-like attribute on the user accounts that contain the names of the groups or roles that the users are members of. In general, this is true for all Microsoft Active Directory servers and all types of Sun directory servers. Unless the LDAP server type is set to Custom using the type parameter, this argument is optional.
--member-attribute=value

For all LDAP servers with support for a memberOf-like attribute, this argument specifies the name of the LDAP attribute on the user account that contains the names of the groups or roles that the user is a member of. In general, this includes all Microsoft Active Directory server and all types of Sun Directory Servers. For Microsoft Active Directory servers, the parameter value defaults to memberOf. For Sun ONE Directory Servers, it defaults to nsRole. For Sun Java System Directory Server version 6.0 or later, it defaults to isMemberOf. To use the roles with the Sun Java System Directory Server, override the default value by setting this argument to nsRole.
198 (276) TIBCO Spotfire Server 5.5

For some LDAP servers with configurations of type Custom , there is no memberOf-like attribute. In those cases, this argument specifies the LDAP attribute on the group account that contains the names of its members. Note: All configurations of this type will use a far less efficient group synchronization algorithm that will generate more traffic to the LDAP servers, because the Spotfire Server will first have to search for the distinguished names (DNs) of the group members within the groups, and then perform repeated lookups to translate the member DN to the correct accountname. Unless the LDAP server type is set to Custom using the type parameter, this argument is optional.
--ignore-member-groups=<true|false>

This argument determines whether the group synchronization mechanism should recursively traverse the synchronized groups non-synchronized subgroups and include their members in the search result or not. For Microsoft Active Directory servers, the parameter value defaults to false so that all inherited group memberships are correctly reflected. For any version of the Sun Directory Servers, it defaults to true, since the role and groups mechanisms in those servers automatically include those members. Unless the LDAP server type is set to Custom using the type parameter, this argument is optional.

config-ldap-userdir
Configures the LDAP User Directory mode. SYNOPSIS
config-ldap-userdir [-c value | --configuration=value] [-b value | --bootstrap-config=value] [-l value | --ldap-configs=value] [-s <true|false> | --group-sync-enabled=<true|false>] [-t value | --sleep-time=value]

OVERVIEW This command is used to configure the LDAP User Directory mode. If no arguments are specified, the command displays the current configuration. OPTIONS
-c value --configuration=value

The path to the server configuration file. This argument is optional. The default value is configuration.xml.
-b value --bootstrap-config=value

The path to the bootstrap configuration file. Refer to bootstrap.xml on page 158. This argument is optional.

TIBCO Spotfire Server 5.5

199 (276)

-l value --ldap-configs=value

A comma-separated list of LDAP configuration references. All referenced LDAP configurations must already exist. To create a new LDAP configuration, use the cre ateldapconfig command. When specifying more than one reference, make sure to enclose the list of references in quotes. This argument is optional.
-s <true|false> --group-sync-enabled=<true|false>

This argument is deprecated and will be ignored. Please use the configldapgroupsync command to enable or disable group synchronization for each LDAP configuration instead. This argument is optional.
-t value --sleep-time=value

The number of minutes between each synchronization. The sleep time setting is only used for LDAP configuration entries without group synchronization schedules. If an LDAP configuration entry has a synchronization schedule defined, then this value is ignored. This argument is optional. The default value is 60.

config-login-dialog
Configures the client login dialog behavior. SYNOPSIS
config-login-dialog [-c value | --configuration=value] [-b value | --bootstrap-config=value] [-s value | --show-login-dialog=value] [-o <true|false> | --allow-work-offline=<true|false>] [-d value | --offline-days-permitted=value] [-r <true|false> | --allow-remember-me=<true|false>] [-u <true|false> | --allow-user-provided-credentials=<true|false>] [-R value | --rss= value]

OVERVIEW This command is used to configure the behavior of the client login dialog. OPTIONS
-c value --configuration=value

The path to the server configuration file. This argument is optional. The default value is configuration.xml.
-b value --bootstrap-config=value

The path to the bootstrap configuration file. Refer to bootstrap.xml on page 158. This argument is optional.
-s value --show-login-dialog=value

Controls whether the login dialog should be displayed or not. Valid values are: always: Show dialog even if user has chosen Savemylogininformation
200 (276) TIBCO Spotfire Server 5.5

never: Never show dialog. Note: Only use this option with one of the single

sign-on methods: NTLM, Kerberos, and X.509 Client Certificates.

standard: Only show dialog if user has not chosen Savemylogininformation

This argument is optional. The default value is standard.

-o <true|false> --allow-work-offline=<true|false>

Controls whether users should be allowed to work offline or if they must always log in. This argument is optional. The default value is true.
-d value --offline-days-permitted=value

Controls for how long users can select to work offline before they are forced to log in. Setting the value to 1 means that users will never be forced to connect to the TIBCO Spotfire Server. This argument is optional. The default value is 1.
-r <true|false> --allow-remember-me=<true|false>

Controls whether users can select to store the login information for future automatic login or if they must always provide user name and password when logging in. This argument is optional. The default value is true.
-u <true|false> --allow-user-provided-credentials=<true|false>

Controls whether users should be able to enter their own credentials in the login dialog or not. This argument is optional. The default value is true.
-R value --rss=value

The URL to an RSS feed to be shown in the login dialog. The feed must be RSS 2.0 compliant. Note that HTML in the RSS feed is not supported. This argument is optional.

config-ntlm-auth
Configures the authentication service used with the NTLM authentication method. SYNOPSIS
config-ntlm-auth [-c value | --configuration=value] [-b value | --bootstrap-config=value] [-S value | --server=value] [-d value | --domain-name=value] [-D value | --domain-controller=value] [-a value | --account-name=value] [-p value | --password=value] [-n value | --dns-servers=value] [-s value | --ad-site=value] [-t value | --dns-cache-ttl=value] [-l value | --localhost-netbios-name=value] [-i value | --connection-id-header-name=value]

OVERVIEW This command is used to configure the authentication service used with NTLM authentication method.

TIBCO Spotfire Server 5.5

201 (276)

OPTIONS
-c value --configuration=value

The path to the server configuration file. This argument is optional. The default value is configuration.xml.
-b value --bootstrap-config=value

The path to the bootstrap configuration file. Refer to bootstrap.xml on page 158. This argument is optional.
-S value --server=value

The name of the cluster server to which the specified configuration parameters should be applied. If no name is specified, the parameters apply to all servers in the cluster. It is typically used to add a server-specific account name or localhost NetBIOS name (see accountname and localhostnetbiosname options). This argument is optional.
-d value --domain-name=value

The DNS name of the Windows domain. The specified domain name will automatically be resolved into domain controller hostnames. It is also possible to use the domaincon troller argument to specify a domain controller hostname directly. The domainname and domaincontroller arguments are mutually exclusive. This argument is mandatory, unless the domaincontroller argument is specified, or if the server argument is specified and this parameter is already specified for the global configuration.
-D value --domain-controller=value

The DNS hostname of an Active Directory domain controller. It is also possible to use the domainname argument to specify a domain name that will automatically be resolved into domain controller hostnames. The domainname and domaincontroller arguments are mutually exclusive. This argument is mandatory, unless the domainname argument is specified, or if the server argument is specified and this parameter is already specified for the global configuration.
-a value --account-name=value

Specifies the fully qualified name of the Active Directory computer account that is to be used by the NTLM authentication service. This account must be a proper computer account created solely for the purpose of running the NTLM authentication service. It can neither be an ordinary user account, nor an account of an existing computer. Note that the name of an Active Directory computer account always contains a dollar-sign, for example [email protected]. The local part of the account name (excluding the dollar-sign) must not exceed 15 characters. Also, because of the dollar-sign, always make sure to enclose this parameter value in quotes and possibly also escape the dollar-sign. If there is more than one server in the cluster, each server must use its own account. Sometimes, it is also possible to share the computer account. The extra servers must then be configured with server-specific localhost NetBIOS names (see the local hostnetbiosname option). Unless the server argument is specified and it is already present in the global configuration, this argument is mandatory.

202 (276)

TIBCO Spotfire Server 5.5

-p value --password=value

Specifies the password for the computer account that is to be used by the NTLM authentication service. This argument is mandatory, unless the server argument is specified and it is already specified for the global configuration.
-n value --dns-servers=value

A comma-separated list of IP addresses for the DNS servers associated with the Windows domain. When no DNS servers are specified, the NTLM authentication service will fall back to the server computers default DNS server configuration. This argument is optional.
-s value --ad-site=value

Specifies the Active Directory Site where the Spotfire system is located. Specifying an Active Directory Site can potentially increase performance, since the NTLM authentication service will then only communicate with the local Domain Controllers. This argument is optional.
-t value --dns-cache-ttl=value

Specifies how long (in milliseconds) name server lookups should be cached. The default value is 5000 ms. This argument is optional.
-l value --localhost-netbios-name=value

Specifies the NetBIOS name, used by each server to identify its connection to the domain controller. The default value is derived from the account name specified by the accountname option. Since the domain controller only allows one connection per NetBIOS name, each additional server after the first must use this option with the server flag to specify a unique localhost NetBIOS name, not exceeding 15 characters in length. The parameter is only necessary to specify when there is more than one server in the cluster. This argument is optional.
-i value --connection-id-header-name=value

This parameter specifies the name of an HTTP header containing unique connection IDs in environments where the server is located behind some kind of proxy or load-balancer that does not properly provide the server with the clients IP address. The specified HTTP header must contain unique connection IDs for each client connection and is thus typically based on the clients IP address and the connections port number on the client side. This parameter is optional. EXAMPLES Configuring the NTLM authentication service for the research.example.com Windows domain:
config.batconfigntlmauthdomainnameresearch.example.comaccountname "ntlmsvc\[email protected]"password53cr3t

TIBCO Spotfire Server 5.5

203 (276)

Configuring the NTLM authentication service for using the Active Directory Domain Controller dc.research.example.com:
configntlmauthdomaincontrollerdc.research.example.comaccountname"ntlmsvc\ [email protected]"password53cr3t

Configuring the NTLM authentication service for the Active Directory Site VIENNA within the research.example.com Windows domain:
configntlmauthdomainnameresearch.example.comaccountname"ntlmsvc\$@ research.example.com"password53cr3tadsite=VIENNA

config-post-auth-filter
Configures the Post Authentication Filter. SYNOPSIS
config-post-auth-filter [-c value | --configuration=value] [-b value | --bootstrap-config=value] [-f value | --filter-class=value] [-s value | --filter-config=value] [-d value | --default-filter-config=value]

OVERVIEW This command is used to configure the Post Authentication Filter. If no argument is provided, the command simply lists the current configuration and exits. OPTIONS
-c value --configuration=value

The path to the server configuration file. This argument is optional. The default value is configuration.xml.
-b value --bootstrap-config=value

The path to the bootstrap configuration file. Refer to bootstrap.xml on page 158. This argument is optional.
-f value --filter-class=value

The fully qualified name of the class implementing the com.spotfire.server.secu rity.PostAuthenticationFilter API. If the argument is none, the current value of this configuration option is cleared. This argument is optional.
-s value --filter-config=value

The filter configuration. The semantics of the configuration argument is specific to the actual filter implementation. For example, it could be a configuration name, a filename or a list of key/value pairs. If the argument is none, the current value of this configuration option is cleared. This argument is optional.

204 (276)

TIBCO Spotfire Server 5.5

-d value --default-filter-config=value

The configuration for the default filter which is always in place. Valid arguments are block and autocreate. See the default filter section below for more information. This argument is optional. THE DEFAULT FILTER IMPLEMENTATION The default implementation of the Post Authentication Filter can be used for access control if you are using an external authentication source, such as LDAP or Windows NT Domain, in combination with the Database User Directory mode. If you are using a different combination of Authentication and User Directory, the filter has no effect. The default implementation has two different modes: The user is allowed access only if he or she already exists in the user directory (to configure this us defaultfilterconfig=block).

The user is allowed access regardless whether he or she already exists in the user directory or not. He or she will then be added to the User Directory (to configure this use defaultfilterconfig=autocreate). .

EXAMPLES Configuring the default filter to block users not in the User Directory (the default behavior):
configpostauthfilter filterclass= com.spotfire.server.security.PostAuthenticationFilterImpl filterconfig=block

Configuring the default filter to automatically create users not in the User Directory:
configpostauthfilterdefaultfilterconfig=autocreate

Configuring a custom filter implementation with the configuration in a file:

configpostauthfilterfilterclass=com.example.MyPostAuthenticationFilter filterconfig="c:\tibco\tss\5.5.0\tomcat\webapps\spotfire\WEBINF\ paf_config.properties"

config-userdir
Configures the User Directory. SYNOPSIS
config-userdir [-c value | --configuration=value] [-b value | --bootstrap-config=value] [-m value | --mode=value] [-C <true|false> | --collapse-domains=<true|false>] [-S <true|false> | --safe-synchronization=<true|false>] [-s value | --domain-name-style= value] [-u <true|false> | --unsafe-domain-name-style-allowed=<true| false>]

OVERVIEW This command is used to configure the User Directory.

TIBCO Spotfire Server 5.5

205 (276)

OPTIONS The arguments are as follows:

-c value --configuration=value

The path to the server configuration file. This argument is optional. The default value is configuration.xml.
-b value --bootstrap-config=value

The path to the bootstrap configuration file. See the bootstrap.xml help topic for more information about this file. This argument is optional.
-m value --mode=value

The name of the User Directory mode to use. Supported values are database, ldap and windows. This argument is optional. The default value is database. The current value will not be changed unless the argument is explicitly specified.
-C value --collapse-domains=value

Indicates whether or not external domains should be collapsed into the internal SPOT FIRE domain, which is the domain used when running the User Directory in database mode. This argument is optional. The default value is false. The current value will not be changed unless the argument is explicitly specified. Note: All users will belong to the same domain when this feature enabled. If there are multiple users with the same account name from different external domains, they will now share Spotfire account. Since this could pose a security problem, this feature should be used with care.
-S <true|false> --safe-synchronization=<true|false>

By setting this option, the User Directory will not disable users that it couldn't find during LDAP or Windows NT synchronization. This flag has no effect if the User Directory is running in Database mode. This argument is optional. The default value is false. The current value will not be changed unless the argument is explicitly specified.
-s value --domain-name-style=value

The domain name style used by the server. Supported values are dns and netbios. This argument is optional. The default value is dns. The current value will not be changed unless the argument is explicitly specified.
-u <true|false> --unsafe-domain-name-style-allowed=<true|false>

By setting this option, the server will allow incompatible domain name style settings, instead of refusing to start. This option should be used with care. It can potentially lead to lots of users and groups being imported to the User Directory with invalid domain names. This argument is optional. The default value is false. The current value will not be changed unless the argument is explicitly specified.

206 (276)

TIBCO Spotfire Server 5.5

config-windows-userdir
Configures the Windows User Directory mode. SYNOPSIS
config-windows-userdir [-c value | --configuration=value] [-b value | --bootstrap-config=value] [-d value | --domains=value] [-t value | --sleep-time=value] [--schedules=value]

OVERVIEW This command is used to configure the Windows User Directory mode. If no arguments are specified, the command displays the current configuration. OPTIONS
-c value --configuration=value

The path to the server configuration file. This argument is optional. The default value is configuration.xml.
-b value --bootstrap-config=value

The path to the bootstrap configuration file. Refer to bootstrap.xml on page 158. This argument is optional.
-d value --domains=value

A comma-separated list of domain names. When specifying more than one domain name, make sure to enclose the list of names in quotes. This argument is optional.
-t value --sleep-time=value

The number of minutes between each synchronization. The sleeptime and sched ules arguments are mutually exclusive. If neither the sleeptime argument nor the schedules argument is specified, the synchronization will be performed with a sleep time of 60 minutes. This argument is optional.
--schedules=value

A comma-separated list of schedules for when the synchronization should be performed. The --sleep-time and --schedules arguments are mutually exclusive. The schedules are given in a cron-compatible format, where each schedule consists of either five fields or one shorthand label. Please make sure to enclose the value in double quotes. This argument is optional. The five fields are, from left to right, with their valid ranges: minute (0-59), hour (0-23), day of month (1-31), month (1-12) and day of week (0-7, where both 0 and 7 indicate Sunday). A field may also be configured with the wildcard character *, indicating that any moment in time matches this field. An LDAP synchronization is triggered when all fields match the current time. If both day of month and day of week have non-wildcard values, then only one of them has to match. There are also the following shorthand labels that can be used instead of the full cron expressions:
TIBCO Spotfire Server 5.5 207 (276)

@yearlyor@annually:runonceayear(equivalentto0011*) @monthly:runonceamonth(equivalentto001**) @weekly:runonceaweek(equivalentto00**0) @dailyor@midnight:runonceaday(equivalentto00***) @hourly:runonceanhour(equivalentto0****) @minutely:runonceaminute(equivalentto*****) @rebootor@restart:runeverytimetheSpotfireServerisstarted

Consult the Wikipedia article for an overview of the cron scheduler:

http://en.wikipedia.org/wiki/Cron

create-default-config
Creates a new server configuration file containing the default configuration. SYNOPSIS
create-default-config [-f | --force] [export file]

OVERVIEW This command is used to export a default server configuration to a file. The configuration in the file can be edited and then imported into the server database using the importconfig command. OPTIONS
-f --force

The force flag indicates whether or not the tool overwrites an existing destination file. This argument is optional.
[export file]

The path to the configuration file to create. This argument is optional. The default value is configuration.xml.

create-jmx-user
Creates a new JMX user account. SYNOPSIS
create-jmx-user [-b value | --bootstrap-config=value] [-t value | --tool-password=value] <-u value | --username=value> [-p value | --password=value] [-l value | --access-level=value]

OVERVIEW This command is used to create a new JMX user account. The account can only be used to access status information for the server through the JMX protocol. It can not be used by users logging in to the server using a Spotfire client or an HTML browser.
208 (276) TIBCO Spotfire Server 5.5

OPTIONS
-b value --bootstrap-config=value

The path to the bootstrap configuration file. Refer to bootstrap.xml on page 158. This argument is optional.
-t value --tool-password=value

The configuration tool password used to decrypt the database password in the boot strap.xml file. If the tool password is omitted, the command will prompt the end-user for it on the console. Refer to bootstrap.xml on page 158. This argument is optional.
-u value --username=value

The name of the JMX user to be created. This argument is mandatory.

-p value --password=value

The new JMX users password. This argument is optional.

-l value --access-level=value

The access level for the user to be created. May be either r or rw. A user with the rw access level may not only read but also modify any writable attributes. This argument is optional. The default value is r.

create-join-db
Configures the default join database. SYNOPSIS
create-join-db [-c value | --configuration=value] [-b value | --bootstrap-config=value] <-t value | --type=value> <-d value | --database-url=value> <-u value | --username=value> [-p value | --password=value] [-i value | --min-connections=value] [-a value | --max-connections=value] [-v | --validate]

OVERVIEW This command is used to configure the default join database. OPTIONS
-c value --configuration=value

The path to the server configuration file. This argument is optional. The default value is configuration.xml.
-b value --bootstrap-config=value

The path to the bootstrap configuration file. Refer to bootstrap.xml on page 158. This argument is optional.

TIBCO Spotfire Server 5.5

209 (276)

-t value --type=value

This argument specifies the database type and the driver to use. Must match the type name of one of the enabled data source templates. This argument is mandatory.
-d value --database-url=value

This argument specifies the JDBC URL to the database. Since this argument usually contains special characters, make sure to escape those characters or enclose the values between quotes. This argument is mandatory.
-u value --username=value

This argument specifies the database accounts username. This argument is mandatory.
-p value --password=value

This argument specifies the database accounts password. This argument is optional.
-i value --min-connections=value

This argument specifies the minimum number of connections to keep in the connection pool. This argument is optional. The default value is 0.
-a value --max-connections=value

This argument specifies the maximum number of connections to keep in the connection pool. This argument is optional. The default value is 0.
-v --validate

This flag indicates whether or not the created configuration should be validated by attempting to connect to the database using the specified connection information. This argument is optional.

create-ldap-config
Creates a new LDAP configuration to be used for authentication and/or the User Directory LDAP provider. SYNOPSIS
create-ldap-config [-c value | --configuration=value] [-b value | --bootstrap-config=value] <--id=value> [--discover] [-t value | --type=value] [-s value | --servers=value] [-n value | --context-names=value] [-u value | --username=value] [-p value | --password=value] [--schedules=value] [--user-search-filter=value] [--user-name-attribute=value] [--authentication-attribute=value] [--security-authentication=value] [--referral-mode=value] [--request-control=value] [--page-size=value] [--import-limit=value] [--user-display-name-attribute=value] [--group-display-name-attribute=value] {-Ckey=value}

210 (276)

TIBCO Spotfire Server 5.5

OVERVIEW This command can be used to create a new LDAP configuration to be used for authentication and/or user directory mode. OPTIONS
-c value --configuration=value

The path to the server configuration file. This argument is optional. The default value is configuration.xml.
-b value --bootstrap-config=value

The path to the bootstrap configuration file. Refer to bootstrap.xml on page 158. This argument is optional.
--id=value

Specifies the identifier for the LDAP configuration to be created. This argument is mandatory.
--discover

This flag can be specified to attempt to automatically create an LDAP configuration based on the information available from the DNS service. The discover mode only works when the desired LDAP server has registered SRV records in the DNS service used by the computer where this command is being invoked. This is typically the case for Active Directory LDAP servers. This flag is optional and mutually exclusive with the t/type, s/servers and n/contextnames flags.
-t value --type=value

The type of LDAP server. The following names are valid types:

ActiveDirectory SunOne SunJavaSystem Custom

When specifying any of the first three types, a type-specific configuration template is automatically applied in runtime, so that the most fundamental configuration options are automatically configured. When specifying a Custom LDAP server type, there is no such configuration template and all those configuration options must be specified explicitly. When a custom LDAP configuration is to be used for authentication or with the User Directory LDAP provider, the usersearchfilter and usernameattribute arguments must be specified. For such an LDAP configuration to be used for group synchronization, additional parameters must also be specified when running the con figldapgroupsync command. See config-ldap-group-sync on page 196. Unless the discover option is used, this argument is mandatory.

TIBCO Spotfire Server 5.5

211 (276)

-s value --servers=value

This argument is used to specify a whitespace-separated list of LDAP server URLs. An LDAP server URL has the format <protocol>://<server>[:<port>]:

<protocol>: Either LDAP or LDAPS <server>: The fully qualified DNS name of the LDAP server. <port>: Optional. Number indicating the port number the LDAP service is listening on. When using the LDAP protocol, the port number defaults to 389. When using the LDAPS protocol, the port number defaults to 636. Active

Directory LDAP servers also provides a Global Catalog containing forest-wide information, instead of domain-wide information only. The Global Catalog LDAP service by default listens on port number 3268 (LDAP) or 3269 (LDAPS). The Spotfire Server does not expect any search base, scope, filter or other additional parameters after the port number in the LDAP server URLs. Such properties are specified using other configuration options for this command. Unless the discover option is used, this argument is mandatory. Examples: LDAP server URLs
LDAP://myserver.example.com LDAPS://myserver.example.com LDAP://myserver.example.com:389 LDAPS://myserver.example.com:636 LDAP://myserver.example.com:3268 LDAPS://myserver.example.com:3269
-n value --context-names=value

A list of distinguished names (DNs) of the containers holding the LDAP accounts to be visible within the Spotfire Server. When specifying more than one DN, then the DNs must be separated by pipe-characters (|). If the specified containers contain a large number of users, of which only a few should be visible in the Spotfire Server, a custom user search filter can be specified to include only the designated users (see the usersearchfilter argument). Unless the discover option is used, this argument is mandatory. Examples:
CN=users,DC=example,DC=com OU=projectx,DC=research,DC=example,DC=com
-u value --username=value

The name of the LDAP service account to be used when searching for users (and optionally also groups) in the LDAP server. This service account does not need to have any write permissions, but it needs to have read permissions for all configured context names (LDAP containers). For most LDAP servers, the account name is the accounts distinguished name (DN). For Active Directory, the account name can also be specified in the forms ntdomain\name and name@dnsdomain. This argument is mandatory. Examples:
212 (276) TIBCO Spotfire Server 5.5

CN=spotsvc,OU=services,DC=research,DC=example,dc=COM RESEARCH\spotsvc(note: Active Directory only) [email protected](note: Active Directory only)

-p value --password=value

The password for the LDAP service account. This argument is optional.
--schedules=value

A comma-separated list of schedules for when the LDAP synchronization should be performed. The schedules are given in a cron-compatible format, where each schedule consists of either five fields or one shorthand label. Please make sure to enclose the value in double quotes. This argument is optional. The default value is @daily, @ restart. The five fields are, from left to right, with their valid ranges: minute (0-59), hour (0-23), day of month (1-31), month (1-12) and day of week (0-7, where both 0 and 7 indicate Sunday). A field may also be configured with the wildcard character *, indicating that any moment in time matches this field. A group synchronization is triggered when all fields match the current time. If both day of month and day of week have non-wildcard values, then only one of them has to match. There are also the following shorthand labels that can be used instead of the full cron expressions:
@yearlyor@annually:runonceayear(equivalentto0011*) @monthly:runonceamonth(equivalentto001**) @weekly:runonceaweek(equivalentto00**0) @dailyor@midnight:runonceaday(equivalentto00***) @hourly:runonceanhour(equivalentto0****) @minutely:runonceaminute(equivalentto*****) @rebootor@restart:runeverytimetheSpotfireServerisstarted

Refer to the Wikipedia overview article on the cron scheduler.

--user-search-filter=value

This parameter specifies an LDAP search expression filter to be used when searching for users.

For Active Directory servers, the parameter value defaults to objectClass=user. For any version of the Sun Directory Servers, it defaults to objectClass=person.

This argument is optional, but it must be specified for custom LDAP configurations, either when running this command or the updateldapconfig command. If only a subset of all the users in the specified LDAP containers should be allowed access to the Spotfire Server, a more detailed user search filter can be used. For example, the search expression can be expanded so that it also puts restrictions on which groups the users belong to, or which roles they have. For Active Directory servers, access can be restricted to only those users belonging to a certain group by using a search expression with the pattern &(objectClass=user)(memberOf=<groupDN>) where <groupDN> is to be replaced
TIBCO Spotfire Server 5.5 213 (276)

by the real DN of the group to which the users must belong. If the users are divided among multiple groups, use the pattern &(objectClass=user)(|(memberOf= <firstDN>)(memberOf=<secondDN>)). Add extra (memberOf=<groupDN>) sub-expressions as needed. Active Directory Example:
&(objectClass=person)(isMemberOf=cn=projectx,dc=example,dc=com)

For a Sun Java System Directory Server version 6 and later, the same effect can be achieved by using a search expression with the pattern &(objectClass= person)(isMemberOf=<groupDN>). If the users are divided among multiple groups, use the pattern &(objectClass=person)(|(isMemberOf= <firstDN>)(isMemberOf=<secondDN>)). Add extra (isMemberOf=<groupDN>) sub-expressions as needed. Sun Java System Directory Server Example:
&(objectClass=person)(isMemberOf=cn=projectx,dc=example,dc=com)

For Sun ONE Directory Servers as well as the newer Sun Java System Directory Servers or the older iPlanet Directory Server, access can be restricted to only those users having certain specific roles. The search expression for role filtering must match the pattern &(objectClass=person)(nsRole=<roleDN>). If multiple roles are of interest, use the pattern &(objectClass=person)(|(nsRole=<firstDN>)(nsRole= <secondDN>). Add extra (nsRole=<roleDN>) sub-expressions as needed. Sun ONE Directory Servers Example:
&(objectClass=person)(isMemberOf=cn=projectx,dc=example,dc=com)

The syntax of LDAP search expression filters is specified by the RFC 4515 document. Please consult this documentation for information about more advanced filters.
--user-name-attribute=value

Specifies the name of the LDAP attribute containing the user account names. For Active Director servers the value defaults to sAMAccountName. For a Sun Java System Directory Server or any older Sun ONE Directory Server or iPlanet Directory Server with a default configuration, it defaults to uid. Unless the LDAP server type is set to Custom using the type parameter, this argument is optional.
--authentication-attribute=value

Specifies the name of the LDAP attribute containing a user identity that can be used for binding (authenticating) to the LDAP server. This attribute fills no purpose in most common LDAP configurations, but can be useful in more advanced setups, where the distinguished name (DN) does not work for authentication or where users should be able to login using a username which does not map directly to an actual LDAP account. When setting up SASL with DIGEST-MD5 in an Active Directory environment, the DN does not work for authentication and the userPrincipalName attribute must be used instead. The authenticationattribute argument should then be set to userPrincipalName and the usernameattribute argument should be set to sAMAccountName (the latter value also happens to be the default value for an Active Directory LDAP configuration, so there is no need to set it explicitly). See also the securityauthentication argument.).

214 (276)

TIBCO Spotfire Server 5.5

When setting up SASL with GSSAPI in an Active Directory environment, the DN does not work for authentication and the sAMAccountName or userPrincipalName attribute must be used instead. The authenticationattribute argument should then be set to sAMAccountName or userPrincipalName and the --user-name-attribute argument should be set to 'sAMAccountName' (the latter value also happens to be the default value for an Active Directory LDAP configuration, so there is no need to set it explicitly). See also the securityauthentication argument.

Example: By setting the usernameattribute argument to cn and the authenticationattribute argument to userPrincipalName in an Active Directory environment, the end-users will be able to login to the Spotfire Server using their CN attribute values, but underneath the hood, the Spotfire Server will actually use the userPrincipalName attribute value of the LDAP account with the matching CN for the actual authentication. This argument is optional and should only be used in advanced setups. It is not set by default.
--security-authentication=value

This argument is optional and should only be used in advanced setups. The default value is simple. This parameter specifies the security level to use when binding to the LDAP server: To enable anonymous binding, it should be set to none.

To enable plain username/password authentication, it should be set to simple. To enable SASL authentication, it should be set to the name of the SASL mechanism to be used, for instance DIGESTMD5 or GSSAPI. Use multiple C flags to set the additional JNDI environment properties that the SASL authentication mechanism typically requires.

When setting up SASL with DIGEST-MD5 in an Active Directory environment, all accounts must use reversible encryption for their passwords. This is typically not the default setting for the domain controller. The authenticationattribute argument must also be used to specify the userPrincipalName attribute for the actual authentication to work correctly. When setting up SASL with GSSAPI in an Active Directory environment, the authenticationattribute argument must be used to specify either the sAMAccount Name or the userPrincipalName attribute and the custom property kerberos.login.con text.name must be mapped to the JAAS application configuration SpotfireGSSAPI. This is turn requires a fully working Kerberos configuration file at <installationdirectory>/ jdk/jre/lib/security/krb5.conf. This argument is optional and should only be used in advanced setups. The default value is simple.
--referral-mode=value

This argument specifies how LDAP referrals should be handled. Valid arguments are follow (automatically follow any referrals), ignore (ignore referrals) and throw (fail

TIBCO Spotfire Server 5.5

215 (276)

with an error). The default and recommended value is follow. This argument is optional.
--request-control=value

This argument determines the type of LDAP controls to be used when executing search queries to the LDAP server. The default behavior is to probe the LDAP server for the best supported request control. The paged results control is always preferred, since it provides the most efficient way of retrieving the querys result set. The virtual list view control can also be used for the same purpose if the paged results control is not supported. The virtual list view control will automatically be used together with a sort control. Both the paged results control and the virtual list view control supports a configurable page size, set by the pagesize argument. To explicitly configure the server for probing, set the argument value to probe.

To configure the server for the paged results control, set the argument value to PagedResultsControl. To request the virtual list view control, set the argument value to VirtualListViewControl. To completely disable request controls by setting the argument value to none.

This argument is optional. The default value is probe.

--page-size=value

This argument specifies the page size to be used with the paged results control or the virtual list view control when performing search queries to the LDAP server. The page size value defaults to 2000 for both the paged results control and the virtual list view control. This argument is optional.
--import-limit=value

This argument specifies a threshold that limits the number of users that can be imported from an LDAP server to the Spotfire Server in one query. This can be used to prevent accidental flooding of the Spotfire Servers User Directory when integrating with an LDAP server with tens or even hundreds of thousands of users. By setting an import limit, the administrator can be sure that an unexpected high number of users wont affect the servers performance. By default, there is no import limit. To explicitly request unlimited import, set the parameter value to 1. All positive numbers are treated as an import limit. In most cases, it is recommended to leave this parameter untouched. This argument is optional.
--user-display-name-attribute=value

Specifies the name of the LDAP attribute containing the user display names. This argument is optional.
--group-display-name-attribute=value

Specifies the name of the LDAP attribute containing the group display names. This argument is optional.
-Ckey=value

This argument specifies additional JNDI environment properties to be used when connecting to the LDAP server. This argument is optional and may be specified multiple times with different keys.

216 (276)

TIBCO Spotfire Server 5.5

Example: The equivalent of specifying the securityauthentication=DIGESTMD5 argument is Cjava.naming.security.authentication=DIGESTMD5. EXAMPLES Create an LDAP configuration for Active Directory:
createldapconfig id="ldap1" type="ActiveDirectory" servers="ldap:// dc01.research.example.com:3268 ldap://dc02.research.example.com:3268" contextnames="OU=projectx,DC=research,DC=example,DC=com|OU=phbs,DC= management,DC=example,DC=com" username="[email protected]" password="s3cr3t"schedules="@daily"

Create an LDAP configuration for SunONE:

createldapconfig id="ldap1" type="SunONE" servers="ldap:// directory.research.example.com:389" contextnames="OU=projectx,DC=research,DC= example,DC=com|OU=phbs,DC=management,DC=example,DC=com" username= "ldapadmin" password="s3cr3t"schedules="@daily"

Create an LDAP configuration for Sun Java System Directory:

createldapconfig id="ldap1" type="SunJavaSystem" servers="ldaps:// directory.research.example.com:636" contextnames="OU=projectx,DC=research,DC= example,DC=com|OU=phbs,DC=management,DC=example,DC=com" username= "ldapadmin" password="s3cr3t"schedules="@daily"

Create an LDAP configuration for a custom LDAP server:

createldapconfig id="ldap1" type="Custom" servers="ldap:// directory.research.example.com"contextnames="OU=projectx,DC=research,DC= example,DC=com|OU=phbs,DC=management,DC=example,DC=com" usernameattribute="cn" searchfilter="&(objectClass=person)(isMemberOf=cn= projectX,dc=example,dc=com)" username="ldapadmin" password="s3cr3t" schedules="@daily"

Create an LDAP configuration using the discover mode:

createldapconfig id="ldap1" discover username="ldapadmin@ research.example.com" password="s3cr3t"schedules="@daily"

create-user
Creates a new user account. SYNOPSIS
create-user [-b value | --bootstrap-config=value] [-t value | --tool-password=value] <-u value | --username=value> [-p value | --password=value] [-d value | --display-name=value] [-e value | --email=value]

OVERVIEW This command is used to create a new user account. This user can then be promoted to administrator using the promoteadmin command.

TIBCO Spotfire Server 5.5

217 (276)

OPTIONS
-b value --bootstrap-config=value

The path to the bootstrap configuration file. Refer to bootstrap.xml on page 158. This argument is optional.
-d value --display-name=value

The new user's display name. This argument is optional.

-e value --email=value

The new user's email address. This argument is optional.

-t value --tool-password=value

The configuration tool password used to decrypt the database password in the bootstrap.xml file. If the tool password is omitted, the command will prompt the end-user for it on the console. Refer to bootstrap.xml on page 158. This argument is optional.
-u value --username=value

The name of the user to be created. This argument is mandatory.

-p value --password=value

The new users password. This argument is optional.

delete-jmx-user
Deletes a JMX user. SYNOPSIS
delete-jmx-user [-b value | --bootstrap-config=value] [-t value | --tool-password=value] <-u value | --username=value>

OVERVIEW This command is used to delete a user which can access the server through JMX. OPTIONS
-b value --bootstrap-config=value

The path to the bootstrap configuration file. Refer to bootstrap.xml on page 158. This argument is optional.

218 (276)

TIBCO Spotfire Server 5.5

-t value --tool-password=value

The configuration tool password used to decrypt the database password in the boot strap.xml file. If the tool password is omitted, the command will prompt the end-user for it on the console. Refer to bootstrap.xml on page 158. This argument is optional.
-u value --username=value

The user name for the user to be deleted. This argument is mandatory.

delete-user
Deletes a user account. SYNOPSIS
delete-user [-b value | --bootstrap-config=value] [-t value | --tool-password=value] <-u value | --username=value>

OVERVIEW This command is used to delete a user account. OPTIONS

-b value --bootstrap-config=value

The path to the bootstrap configuration file. Refer to bootstrap.xml on page 158. This argument is optional.
-t value --tool-password=value

The configuration tool password used to decrypt the database password in the boot strap.xml file. If the tool password is omitted, the command will prompt the end-user for it on the console. This argument is optional.
-u value --username=value

The name of the user to be deleted. This argument is mandatory.

demote-admin
Revokes full administrator privileges from a user. SYNOPSIS
demote-admin [-b value | --bootstrap-config=value] [-t value | --tool-password=value] <-u value | --username=value>

OVERVIEW This command is used to revoke administrator privileges for a user by removing the user account from the Administrator group.
TIBCO Spotfire Server 5.5 219 (276)

OPTIONS
-b value --bootstrap-config=value

The path to the bootstrap configuration file. Refer to bootstrap.xml on page 158. This argument is optional.
-t value --tool-password=value

The configuration tool password used to decrypt the database password in the boot strap.xml file. If the tool password is omitted, the command will prompt the end-user for it on the console. Refer to bootstrap.xml on page 158. This argument is optional.
-u value --username=value

The name of the user for which to revoke the administrator privileges. Unless the user is part of the configured default domain, the name of the user needs to include the user's domain name, for instance DOMAIN\user or user@domain. This argument is mandatory.

enable-user
Enables or disables a user in the Spotfire Database. SYNOPSIS
enable-user [-b value | --bootstrap-config=value] [-t value | --tool-password=value] [-u value | --username=value] [-a | --all] [-e <true|false> | --enabled=<true|false>]

OVERVIEW This command is used to enable or disable a user in the Spotfire Database. A disabled user does not have any access to the Spotfire Server. OPTIONS The arguments are as follows:
-b value --bootstrap-config=value

The path to the bootstrap configuration file. See the bootstrap.xml help topic for more information about this file. This argument is optional.
-t value --tool-password=value

The configuration tool password used to decrypt the database password in the bootstrap.xml file. If the tool password is omitted, the command will prompt the end-user for it on the console. See the bootstrap.xml help topic for more information. This argument is optional.

220 (276)

TIBCO Spotfire Server 5.5

-u value --username=value

The user that should be enabled or disabled. Should not be specified if the all-flag is used. This argument is optional.
-a --all

Updates the enabled status for all the users. If this flag is present, no username should be specified. This argument is optional.
-e <true|false> --enabled=<true|false>

If the user should be enabled or disabled. This argument is optional. The default value is true.

export-config
Exports a server configuration from the server database to the current working directory as a configuration.xml file. SYNOPSIS
export-config [-f | --force] [-b value | --bootstrap-config=value] [-t value | --tool-password=value] [-h value | --hash=value] [export file]

OVERVIEW This command is used to export a server configuration from the server database to a file. The configuration in the file can be edited and then imported back into the server database using the importconfig command. OPTIONS
-f --force

The force flag indicates whether or not the tool overwrites an existing destination file. This argument is optional.
-b value --bootstrap-config=value

The path to the bootstrap configuration file. Refer to bootstrap.xml on page 158. This argument is optional.
-t value --tool-password=value

The configuration tool password used to decrypt the database password in the boot strap.xml file. If the tool password is omitted, the command will prompt the end-user for it on the console. Refer to bootstrap.xml on page 158. This argument is optional.

TIBCO Spotfire Server 5.5

221 (276)

-h value --hash=value

The (possibly abbreviated) hash of the configuration to export. Must consist of at least 6 hexadecimal characters. This argument is optional.
[export file]

The path to the configuration file to create. This argument is optional. The default value is configuration.xml.

export-ds-template
Exports the definition of a data source template. SYNOPSIS
export-ds-template [-f | --force] [-c value | --configuration=value] [-b value | --bootstrap-config=value] <-n value | --name=value> [template definition file]

OVERVIEW This command is used to export the definition of a data source template used by Information Services to a file. OPTIONS
-f --force

The force flag indicates whether or not the tool overwrites an existing destination file. This argument is optional.
-c value --configuration=value

The path to the server configuration file. This argument is optional. The default value is configuration.xml.
-b value --bootstrap-config=value

The path to the bootstrap configuration file. Refer to bootstrap.xml on page 158. This argument is optional.
-n value --name=value

The name of the data source template for which to export the definition. This argument is mandatory.
[template definition file]

The path to the definition file to create. This argument is optional. The default value is template.xml.

222 (276)

TIBCO Spotfire Server 5.5

export-groups
Exports groups from the User Directory. SYNOPSIS
export-groups [-b value | --bootstrap-config=value] [-t value | --tool-password=value] [-m <true|false> | --include-member-groups= <true|false>] [-u <true|false> | --include-member-users=<true|false>] [-g <true|false> | --include-guids=<true|false>] [-s <true|false> | --use-stdf=<true|false>] [-n <true|false> | --include-name-row=<true| false>] [export file] [-f | --force]

OVERVIEW This command is used to export all groups from the User Directory. The exported groups may be imported on a different server. OPTIONS The arguments are as follows:
-b value --bootstrap-config=value

The path to the bootstrap configuration file. See the bootstrap.xml help topic for more information about this file. This argument is optional.
-t value --tool-password=value

The configuration tool password used to decrypt the database password in the bootstrap.xml file. If the tool password is omitted, the command will prompt the end-user for it on the console. See the bootstrap.xml help topic for more information. This argument is optional.
-m <true|false> --include-member-groups=<true|false>

Indicates whether the group hierarchy information (groups in groups) should be included or not. May be used in conjunction with the includememberusers flag to include all information. This argument is optional. The default value is false.
-u <true|false> --include-member-users=<true|false>

Indicates whether the group hierarchy information (users in groups) should be included or not. May be used in conjunction with the includemembergroups flag to include all information. This argument is optional. The default value is false.
-g <true|false> --include-guids=<true|false>

Indicates whether the Globally Unique Identifier (GUID) of each group should be included or not. This argument is optional. The default value is false.

TIBCO Spotfire Server 5.5

223 (276)

-s <true|false> --use-stdf=<true|false>

Indicates whether the exported file should be created in Spotfire Text Data Format or not. If false plain CSV format will be used. This argument is optional. The default value is true.
-n <true|false> --include-name-row=<true|false>

Indicates whether the exported file should include a column name row or not. Only applicable when usestdf is set to false since STDF always includes a name row. This argument is optional. The default value is false.
[export file]

The path to the file to create. This argument is optional. The default value is groups.txt.
-f --force

The force flag indicates whether or not the tool overwrites an existing destination file. This argument is optional.

export-library-content
Exports content from the library. SYNOPSIS
export-library-content [-f | --force] [-b value | --bootstrap-config= value] [-t value | --tool-password=value] <-p value | --file-path= value> <-u value | --user=value> [-a <true|false> | --include-access-rights=<true|false>] [-i value | --item-type=value] <-l value | --library-path=value>

OVERVIEW This command is used to export content from the library. OPTIONS The arguments are as follows:
-f --force

When this flag is specified, the tool will overwrite any already existing file with the same name as specified in the path argument. All parts of the existing file (path.part0.zip, path.part1.zip etc) will also be deleted. This argument is optional.
-b value --bootstrap-config=value

The path to the bootstrap configuration file. See the bootstrap.xml help topic for more information about this file. This argument is optional.

224 (276)

TIBCO Spotfire Server 5.5

-t value --tool-password=value

The configuration tool password used to decrypt the database password in the bootstrap.xml file. Can be specified if and only if a password is given and -enablecon figtool flag is set to true (the default). This argument is optional.
-p value --file-path=value

The file system path to where the item should be exported. This argument is mandatory.
-u value --user=value

The user performing the export, should be a Library Administrator. The name of the user needs to include the user's domain name, for example DOMAIN\user or user@ domain, unless the user is part of the configured default domain. This argument is mandatory.
-a <true|false> --include-access-rights=<true|false>

If access rights should be exported or not. This argument is optional. The default value is true.
-i value --item-type=value

Which item types that should be exported from the library. It is possible to export all items, or all items of a certain type, from a folder. It is also possible to export a single item of a certain type. When exporting the content of a folder, valid values are: all_items, colorschemes, information_model, analysis_files and datafunctions. When exporting a single item, valid values are: analyticitem, dxpscript, bookmark, embeddedresource, query, join, dxp, datafunction, folder, colorscheme, column, datasource, filter and procedure. This argument is optional. The default value is all_items.
-l value --library-path=value

The path in the library where the content will be exported from. When exporting folder content, a path to the folder must be specified. When exporting a single item, a path to that specific item must be specified. The path must start with a slash (/). If the entire library should be exported the path should be /. This argument is mandatory.

export-users
Exports users from the User Directory. SYNOPSIS
export-users [-b value | --bootstrap-config=value] [-t value | --tool-password=value] [-i value | --include-password-hashes=value] [-s value | --use-stdf=value] [-g value | --include-guids=value] [-n value | --include-name-row=value] [export file] [-f | --force]

TIBCO Spotfire Server 5.5

225 (276)

OVERVIEW This command is used to export all users from the User Directory. The exported users may be imported on a different server. OPTIONS The arguments are as follows:
-b value --bootstrap-config=value

The path to the bootstrap configuration file. See the bootstrap.xml help topic for more information about this file. This argument is optional.
-t value --tool-password=value

The configuration tool password used to decrypt the database password in the boot strap.xml file. If the tool password is omitted, the command will prompt the end-user for it on the console. See the bootstrap.xml help topic for more information. This argument is optional.
-i value --include-password-hashes=value

Indicates whether the exported file should include the password hashes. Passwords are only relevant if you use the Spotfire database for authentication. This argument is optional. The default value is false.
-s value --use-stdf=value

Indicates whether the exported file should be created in Spotfire Text Data Format or not. If false plain CSV format will be used. This argument is optional. The default value is true.
-g value --include-guids=value

Indicates whether the Globally Unique Identifier (GUID) of each user should be included or not. This argument is optional. The default value is false.
-n value --include-name-row=value

Indicates whether the exported file should include a column name row or not. Only applicable when usestdf is set to false since STDF always includes a name row. This argument is optional. The default value is false.
[export file]

The path to the file to create. This argument is optional. The default value is users.txt.
-f --force

The force flag indicates whether or not the tool overwrites an existing destination file. This argument is optional.

226 (276)

TIBCO Spotfire Server 5.5

help
Displays the help overview or a specific help topic. SYNOPSIS
help [topic name]

OVERVIEW This command is used to display the help overview or a specific help topic. OPTIONS
[topic name]

The name of the help topic to be displayed. This argument is optional.

import-config
Imports a server configuration from a file to the server database. SYNOPSIS
import-config [-b value | --bootstrap-config=value] [-t value | --tool-password=value] <-c value | --comment=value> [import file]

OVERVIEW This command is used to import a server configuration from a file to the server database and setting it as the current configuration. Such a server configuration file can be generated either by running the exportconfig command or by creating a new default configuration using the createdefaultconfig command. If an identical configuration file already exist in the server database the existing configuration will get its description updated. OPTIONS
-b value --bootstrap-config=value

The path to the bootstrap configuration file. Refer to bootstrap.xml on page 158. This argument is optional.
-t value --tool-password=value

The configuration tool password used to decrypt the database password in the boot strap.xml file. If the tool password is omitted, the command will prompt the end-user for it on the console. Refer to bootstrap.xml on page 158. This argument is optional.
-c value --comment=value

A comment describing the reason for the configuration change. Please make sure to enclose the specified comment in quotes and to quote all special characters that might otherwise be consumed by the command line shell. This argument is mandatory.

TIBCO Spotfire Server 5.5

227 (276)

[import file]

The path to the configuration file to import. This argument is optional. The default value is configuration.xml.

import-groups
Imports groups to the User Directory. SYNOPSIS
import-groups [-b value | --bootstrap-config=value] [-t value | --tool-password=value] [-m <true|false> | --include-member-groups= <true|false>] [-u <true|false> | --include-member-users=<true|false>] [-g <true|false> | --include-guids=<true|false>] [-n <true|false> | --has-name-row=<true|false>] [import file]

OVERVIEW This command is used to import all groups in a given file to the User Directory. The groups may be imported including membership information or as a simple list. OPTIONS The arguments are as follows:
-b value --bootstrap-config=value

The path to the bootstrap configuration file. See the bootstrap.xml help topic for more information about this file. This argument is optional.
-t value --tool-password=value

The configuration tool password used to decrypt the database password in the boot strap.xml file. If the tool password is omitted, the command will prompt the end-user for it on the console. See the bootstrap.xml help topic for more information. This argument is optional.
-m <true|false> --include-member-groups=<true|false>

Indicates whether the group hierarchy information (groups in groups) should be included or not. May be used in conjunction with the includememberusers flag to include all information. This argument is optional. The default value is false.
-u <true|false> --include-member-users=<true|false>

Indicates whether the group hierarchy information (users in groups) should be included or not. May be used in conjunction with the includemembergroups flag to include all information. This argument is optional. The default value is false.
-g <true|false> --include-guids=<true|false>

Indicates whether Globally Unique Identifiers (GUIDs) in the file should be included or not. This argument is optional. The default value is false.

228 (276)

TIBCO Spotfire Server 5.5

-n <true|false> --has-name-row=<true|false>

Indicates whether the file contains a name row or not. Only applicable when the file is in plain CSV format since the Spotfire Text Data Format (STDF) always has a name row. This argument is optional. The default value is false.
[import file]

The path to the file to import. This argument is optional. The default value is groups.txt.

import-jaas-config
Imports new JAAS application configurations into the server configuration. SYNOPSIS
import-jaas-config [-c value | --configuration=value] [-b value | --bootstrap-config=value] [-f | --force] <-j value | --jaas-config-file=value> [-n value | --name=value]

OVERVIEW This command is used to import new JAAS application configurations into the server configurations. OPTIONS
-c value --configuration=value

The path to the server configuration file. This argument is optional. The default value is configuration.xml.
-b value --bootstrap-config=value

The path to the bootstrap configuration file. Refer to bootstrap.xml on page 158. This argument is optional.
-f --force

The force flag indicates whether or not the JAAS application configurations should be imported into the server even if other configurations with the same names already exist. When this flag is enabled, the old configurations will be overwritten. This argument is optional.
-j value --jaas-config-file=value

The path to the JAAS application configuration file. The file is expected to be in the standard JAAS application configuration format This argument is mandatory.
-n value --name=value

The names of the JAAS application configurations to be imported into the server. Multiple names must be comma-separated and enclosed between quotes. If this argument

TIBCO Spotfire Server 5.5

229 (276)

is omitted, then all JAAS application configurations within the specified file will be imported. This argument is optional.

import-library-content
Imports content into the library. SYNOPSIS
import-library-content [-b value | --bootstrap-config=value] [-t value | --tool-password=value] <-p value | --file-path=value> <-m value | --conflict-resolution-mode=value> <-u value | --user=value> [-e <true|false> | --prune-empty-directories=<true|false>] [-a <true| false> | --include-access-rights=<true|false>] [-i value | --item-type=value] [-l value | --library-path=value]

OVERVIEW This command is used to import content into the library. OPTIONS The arguments are as follows:
-b value --bootstrap-config=value

The path to the bootstrap configuration file. See the bootstrap.xml help topic for more information about this file. This argument is optional.
-t value --tool-password=value

The configuration tool password used to decrypt the database password in the bootstrap.xml file. Can be specified if and only if a password is given and enablecon figtool flag is set to true (the default). This argument is optional.
-p value --file-path=value

The file system path to the file that should be imported into the library. This should be the result of a previous library export and with a name ending with .part0.zip. If the export consists of several parts (ending with .part1.zip etc.) these must be placed in the same folder. This argument is mandatory.
-m value --conflict-resolution-mode=value

Sets the conflict resolution mode that should be used if there is a conflict with already existing content in the library path given. The conflict resolution mode will be applied for each conflicting item that is imported. Valid values are: KEEP_NEW, KEEP_OLD and KEEP_BOTH. This argument is mandatory.
-u value --user=value

The user performing the import, should be a Library Administrator. Unless the user is part of the configured default domain, the name of the user needs to include the user's domain name, like DOMAIN\user or user@domain. This argument is mandatory.
230 (276) TIBCO Spotfire Server 5.5

-e <true|false> --prune-empty-directories=<true|false>

If empty directories should be created or not. This argument is optional. The default value is false.
-a <true|false> --include-access-rights=<true|false>

If access rights should be imported or not. This argument is optional. The default value is true.
-i value --item-type=value

Which item types that should be imported into the library. Valid values are: all_items, colorschemes, information_model, analysis_files and datafunctions. This argument is optional. The default value is all_items.
-l value --library-path=value

The path in the library where the content will be imported. The path must specify an existing folder in the library. This argument is optional. The default value is /.

import-users
Imports users to the User Directory. SYNOPSIS
import-users [-b value | --bootstrap-config=value] [-t value | --tool-password=value] [-i <true|false> | --include-passwords=<true| false>] [-h <true|false> | --hash-passwords=<true|false>] [-g <true| false> | --include-guids=<true|false>] [-n <true|false> | --has-name-row=<true|false>] [import file]

OVERVIEW This command is used to import all users in a given file to the User Directory. The users may be imported with or without passwords. OPTIONS The arguments are as follows:
-b value --bootstrap-config=value

The path to the bootstrap configuration file. See the bootstrap.xml help topic for more information about this file. This argument is optional.
-t value --tool-password=value

The configuration tool password used to decrypt the database password in the boot strap.xml file. If the tool password is omitted, the command will prompt the end-user for it on the console. See the bootstrap.xml help topic for more information. This argument is optional.

TIBCO Spotfire Server 5.5

231 (276)

-i <true|false> --include-passwords=<true|false>

Indicates whether passwords in the file should be included or not. This argument is optional. The default value is false.
-h <true|false> --hash-passwords=<true|false>

Indicates whether the included passwords should be hashed during import or not. Should be false if the users have previously been exported from a TIBCO Spotfire Server since those passwords are already hashed. This argument is optional. The default value is false.
-g <true|false> --include-guids=<true|false>

Indicates whether Globally Unique Identifiers (GUIDs) in the file should be included or not. This argument is optional. The default value is false.
-n <true|false> --has-name-row=<true|false>

Indicates whether the file contains a name row or not. Only applicable when the file is in plain CSV format since the Spotfire Text Data Format (STDF) always has a name row. This argument is optional. The default value is false.
[import file]

The path to the file to import. This argument is optional. The default value is users.txt.

list-admins
Lists the server administrators. SYNOPSIS
list-admins [-b value | --bootstrap-config=value] [-t value | --tool-password=value]

OVERVIEW This command is used to list the server administrators. Only direct members of the Administrator group are shown. OPTIONS
-b value --bootstrap-config=value

The path to the bootstrap configuration file. Refer to bootstrap.xml on page 158. This argument is optional.
-t value --tool-password=value

The configuration tool password used to decrypt the database password in the boot strap.xml file. If the tool password is omitted, the command will prompt the end-user for it on the console. Refer to bootstrap.xml on page 158. This argument is optional.

232 (276)

TIBCO Spotfire Server 5.5

list-auth-config
Displays the current authentication configuration. SYNOPSIS
list-auth-config [-c value | --configuration=value] [-b value | --bootstrap-config=value]

OVERVIEW This command is used to display the current authentication configuration. OPTIONS The arguments are as follows:
-c value --configuration=value

The path to the server configuration file. This argument is optional. The default value is configuration.xml.
-b value --bootstrap-config=value

The path to the bootstrap configuration file. See the bootstrap.xml help topic for more information about this file. This argument is optional.

list-auth-mode
Displays the currently configured authentication mode. Note: This command is deprecated from 5.0 and is replaced by the list-auth-config on page 233 command. SYNOPSIS
list-auth-mode [-c value | --configuration=value] [-b value | --bootstrap-config=value]

OVERVIEW This command is used to display the configured authentication mode. OPTIONS
-c value --configuration=value

The path to the server configuration file. This argument is optional. The default value is configuration.xml.
-b value --bootstrap-config=value

The path to the bootstrap configuration file. Refer to bootstrap.xml on page 158. This argument is optional.
TIBCO Spotfire Server 5.5 233 (276)

list-configs
Lists all available server configurations. SYNOPSIS
list-configs [-b value | --bootstrap-config=value] [-t value | --tool-password=value] [-i | --include-incompatible] [-h value | --hash-abbrev=value]

OVERVIEW This command is used to list the available configurations. The current configuration is indicated by an asterisk in the leftmost column. OPTIONS
-b value --bootstrap-config=value

The path to the bootstrap configuration file. Refer to bootstrap.xml on page 158. This argument is optional.
-t value --tool-password=value

The configuration tool password used to decrypt the database password in the boot strap.xml file. If the tool password is omitted, the command will prompt the end-user for it on the console. Refer to bootstrap.xml on page 158. This argument is optional.
-i --include-incompatible

Indicates whether or not to include configurations incompatible with the current server version. This argument is optional.
-h value --hash-abbrev=value

The number of hexadecimal digits (between 6 and 40) to abbreviate the configuration hash to. This argument is optional. The default value is 7.

list-deployment-areas
Lists the deployment areas SYNOPSIS
list-deployment-areas [-b value | --bootstrap-config=value] [-t value | --tool-password=value]

OVERVIEW This command is used to list the deployment areas as well as display what area that is the default deployment area.

234 (276)

TIBCO Spotfire Server 5.5

OPTIONS The arguments are as follows:

-b value --bootstrap-config=value

The path to the bootstrap configuration file. See the bootstrap.xml help topic for more information about this file. This argument is optional.
-t value --tool-password=value

The configuration tool password used to decrypt the database password in the bootstrap.xml file. If the tool password is omitted, the command will prompt the end-user for it on the console. See the bootstrap.xml help topic for more information. This argument is optional.

list-ds-template
Lists the data source templates. SYNOPSIS
list-ds-template [-c value | --configuration=value] [-b value | --bootstrap-config=value]

OVERVIEW This command is used to list the data source templates. OPTIONS
-c value --configuration=value

The path to the server configuration file. This argument is optional. The default value is configuration.xml.
-b value --bootstrap-config=value

The path to the bootstrap configuration file. Refer to bootstrap.xml on page 158. This argument is optional.

list-groups
Lists all groups. SYNOPSIS
list-groups [-l value | --limit=value] [-s value | --search-expression= value] [-b value | --bootstrap-config=value] [-t value | --tool-password=value]

TIBCO Spotfire Server 5.5

235 (276)

OVERVIEW This command is used to list all groups in the user directory. OPTIONS
-l value --limit=value

The maximum number of groups to list. This argument is optional. The default value is 20.
-s value --search-expression=value

A search expression that may be used to search only for groups with names matching the expression. This argument is optional.
-b value --bootstrap-config=value

The path to the bootstrap configuration file. Refer to bootstrap.xml on page 158. This argument is optional.
-t value --tool-password=value

The configuration tool password used to decrypt the database password in the bootstrap.xml file. If the tool password is omitted, the command will prompt the end-user for it on the console. Refer to bootstrap.xml on page 158. This argument is optional.

list-jaas-config
Lists the JAAS application configurations. SYNOPSIS
list-jaas-config [-c value | --configuration=value] [-b value | --bootstrap-config=value] [--xml] [JAAS application configuration name]

OVERVIEW This command is used to display the servers JAAS application configurations. It cannot display system JAAS application configurations. OPTIONS
-c value --configuration=value

The path to the server configuration file. This argument is optional. The default value is configuration.xml.
-b value --bootstrap-config=value

The path to the bootstrap configuration file. Refer to bootstrap.xml on page 158. This argument is optional.

236 (276)

TIBCO Spotfire Server 5.5

--xml

This flag is specified if the JAAS application configurations should be displayed in XML format, as it is stored within the configuration.xml file. This argument is optional.
[JAAS application configuration name]

The names of the JAAS application configuration to be displayed. Multiple names must be comma-separated and enclosed between quotes. If this argument is omitted, then all JAAS application configurations will be displayed. This argument is optional.

list-jmx-users
Lists all JMX users. SYNOPSIS
list-jmx-users [-b value | --bootstrap-config=value] [-t value | --tool-password=value]

OVERVIEW This command is used to list all users which can access the server through JMX. The result contains the user name and the access level of each user. OPTIONS
-b value --bootstrap-config=value

The path to the bootstrap configuration file. Refer to bootstrap.xml on page 158. This argument is optional.
-t value --tool-password=value

The configuration tool password used to decrypt the database password in the bootstrap.xml file. If the tool password is omitted, the command will prompt the end-user for it on the console. Refer to bootstrap.xml on page 158. This argument is optional.

list-ldap-config
Displays LDAP configurations. SYNOPSIS
list-ldap-config [-c value | --configuration=value] [-b value | --bootstrap-config=value] [--xml=value] [LDAP configuration id]

OVERVIEW This command can be used to display all LDAP configurations.

TIBCO Spotfire Server 5.5

237 (276)

OPTIONS
-c value --configuration=value

The path to the server configuration file. This argument is optional. The default value is configuration.xml.
-b value --bootstrap-config=value

The path to the bootstrap configuration file. Refer to bootstrap.xml on page 158. This argument is optional.
--xml=value

Specifies that the LDAP configuration should be displayed in XML format instead of the standard JAAS application configuration format. This argument is optional.
[LDAP configuration id]

Specifies the identifier of the LDAP configuration to be displayed. If no identifier is specified, then all LDAP configurations are displayed. This argument is optional.

list-ldap-userdir-config
Lists the configuration for the User Directory LDAP mode. SYNOPSIS
list-ldap-userdir-config [-c value | --configuration=value] [-b value | --bootstrap-config=value]

OVERVIEW This command is used to list the configuration for the User Directory LDAP mode. OPTIONS The arguments are as follows:
-c value --configuration=value

The path to the server configuration file. This argument is optional. The default value is configuration.xml.
-b value --bootstrap-config=value

The path to the bootstrap configuration file. See the bootstrap.xml help topic for more information about this file. This argument is optional.

list-ntlm-auth
Displays the NTLM authentication service configuration.

238 (276)

TIBCO Spotfire Server 5.5

SYNOPSIS
list-ntlm-auth [-c value | --configuration=value] [-b value | --bootstrap-config=value] [-S value | --server=value]

OVERVIEW This command is used to display the NTLM authentication service configuration. OPTIONS
-c value --configuration=value

The path to the server configuration file. This argument is optional. The default value is configuration.xml.
-b value --bootstrap-config=value

The path to the bootstrap configuration file. Refer to bootstrap.xml on page 158. This argument is optional.
-S value --server=value

The name of the cluster server whose configuration should be displayed. If no name is specified, the global parameters common to all servers in the cluster will be displayed. This argument is optional.

list-online-servers
Lists all online servers. SYNOPSIS
list-online-servers [-b value | --bootstrap-config=value] [-t value | --tool-password=value]

OVERVIEW This command is used to list all servers in the cluster that are currently online. OPTIONS
-b value --bootstrap-config=value

The path to the bootstrap configuration file. Refer to bootstrap.xml on page 158. This argument is optional.
-t value --tool-password=value

The configuration tool password used to decrypt the database password in the boot strap.xml file. If the tool password is omitted, the command will prompt the end-user for it on the console. Refer to bootstrap.xml on page 158. This argument is optional.

TIBCO Spotfire Server 5.5

239 (276)

OUTPUT A table of all servers in the cluster that are currently online. An asterisk in the leftmost column is used to indicate that the server is the current primus server - responsible for handling tasks like synchronization of LDAP groups. Example:
P * Server Name server1.example.com server2.example.com server3.example.com IP Address 192.0.2.1 192.0.2.2 192.0.2.3 Version 5.5.0.70 5.5.0.60 5.5.0.70

list-post-auth-filter
Displays the current Post Authentication Filter configuration. SYNOPSIS
list-post-auth-filter [-c value | --configuration=value] [-b value | --bootstrap-config=value]

OVERVIEW This command is used to display the Post Authentication Filter configuration. OPTIONS
-c value --configuration=value

The path to the server configuration file. This argument is optional. The default value is configuration.xml.
-b value --bootstrap-config=value

The path to the bootstrap configuration file. Refer to bootstrap.xml on page 158. This argument is optional.

list-userdir-config
Lists the current User Directory configuration. SYNOPSIS
list-userdir-config [-c value | --configuration=value] [-b value | --bootstrap-config=value]

OVERVIEW This command is used to list the current User Directory configuration.

240 (276)

TIBCO Spotfire Server 5.5

OPTIONS The arguments are as follows:

-c value --configuration=value

The path to the server configuration file. This argument is optional. The default value is configuration.xml.
-b value --bootstrap-config=value

The path to the bootstrap configuration file. See the bootstrap.xml help topic for more information about this file. This argument is optional.

list-userdir-mode
Lists the currently configured User Directory mode. Note: This command is deprecated and is replaced by the list-userdir-config on page 240 command. SYNOPSIS
list-userdir-mode [-c value | --configuration=value] [-b value | --bootstrap-config=value]

OVERVIEW This command is used to list the currently configured User Directory mode. OPTIONS
-c value --configuration=value

The path to the server configuration file. This argument is optional. The default value is configuration.xml.
-b value --bootstrap-config=value

The path to the bootstrap configuration file. Refer to bootstrap.xml on page 158. This argument is optional.

list-users
Lists all users. SYNOPSIS
list-users [-f | --force-synchronization] [-l value | --limit=value] [-s value | --search-expression=value] [-b value | --bootstrap-config=value] [-t value | --tool-password=value]

TIBCO Spotfire Server 5.5

241 (276)

OVERVIEW This command is used to list all users in the user directory. It does not work when using the User Directory Windows provider. OPTIONS
-f --force-synchronization

The force flag indicates whether or not the command should force a User Directory synchronization before attempting to list the users. This argument has no effect if the User Directory is running in database mode. This argument is optional.

-l value --limit=value

The maximum number of users to list. This argument is optional. The default value is 100.
-s value --search-expression=value

A search expression that may be used to search only for users with names matching the expression. This argument is optional.
-b value --bootstrap-config=value

The path to the bootstrap configuration file. Refer to bootstrap.xml on page 158. This argument is optional.
-t value --tool-password=value

The configuration tool password used to decrypt the database password in the bootstrap.xml file. If the tool password is omitted, the command will prompt the end-user for it on the console. Refer to bootstrap.xml on page 158. This argument is optional.

list-windows-userdir-config
Lists the configuration for the User Directory Window NT mode. SYNOPSIS
list-windows-userdir-config [-c value | --configuration=value] [-b value | --bootstrap-config=value]

OVERVIEW This command is used to list the configuration for the User Directory Windows NT mode. OPTIONS The arguments are as follows:
242 (276) TIBCO Spotfire Server 5.5

-c value --configuration=value

The path to the server configuration file. This argument is optional. The default value is configuration.xml.
-b value --bootstrap-config=value

The path to the bootstrap configuration file. See the bootstrap.xml help topic for more information about this file. This argument is optional.

manage-deployment-areas
Manages the deployment areas SYNOPSIS manage-deployment-areas [-b value | --bootstrap-config=value] [-t value | --tool-password=value] [-R | --reset-all-group-areas] [-r | --reset-group-area] [-s | --set-group-area] [-c | --create-area] [-D | --delete-area] [-d | --default-area] [-g value | --group-name=value] [-a value | --area-name=value] OVERVIEW This command is used to change deployment area for groups, change default area, create and remove areas. OPTIONS The arguments are as follows:
-b value --bootstrap-config=value

The path to the bootstrap configuration file. See the 'bootstrap.xml' help topic for more information about this file. This argument is optional.
-t value --tool-password=value

The configuration tool password used to decrypt the database password in the bootstrap.xml file. If the tool password is omitted, the command will prompt the end-user for it on the console. See the 'bootstrap.xml' help topic for more information. This argument is optional.
-R --reset-all-group-areas

This flag is used if all specified areas for all groups should be removed. Note: this does not affect the default area or any content on the areas. Users will be using the default area after running this command. This argument is optional.
-r --reset-group-area

This flag is used if an area for a specific group should be removed. Note: this does not affect the default area or any content on the area. If a user is not a member of any group with a specified area, the default area will be used. This argument is optional.

TIBCO Spotfire Server 5.5

243 (276)

-s --set-group-area

This flag is used if an area should be set for a specific group. A user that is a member of this group will get access to the specified area instead of the default area. This argument is optional.
-c --create-area

This flag specifies that a new area should be created. This argument is optional.
-D --delete-area

This flag specifies that an existing area should be deleted. This argument is optional.
-d --default-area

This flag specifies that a the default area should be changed. This argument is optional.
-g value --group-name=value

The name of the group. Applicable for the following flags: reset-all-group-areas, reset-group-area, and set-group-area. This argument is optional.
-a value --area-name=value

The name of the area. Applicable for the following flags: set-group-area, create-area, delete-area, and default-area. This argument is optional.

modify-db-config
Modifies the common database connection configuration. SYNOPSIS
modify-db-config [-c value | --configuration=value] [-b value | --bootstrap-config=value] [-l value | --login-timeout=value] [-o value | --connection-timeout=value] [-i value | --min-connections= value] [-a value | --max-connections=value] [-p value | --pooling-scheme=value] [-q value] {-Ckey=value} [-e <true|false> | --clear-connection-properties=<true|false>]

OVERVIEW This command is used to modify the common configuration for the connection to the Spotfire Server database. This configuration (which effects all servers) will be merged with the configuration in the bootstrap.xml file on each server. OPTIONS
-c value --configuration=value

The path to the server configuration file. This argument is optional. The default value is configuration.xml.

244 (276)

TIBCO Spotfire Server 5.5

-b value --bootstrap-config=value

The path to the bootstrap configuration file. Refer to bootstrap.xml on page 158. This argument is optional.
-l value --login-timeout=value

The maximum time (in seconds) to wait for a connection to become available. This argument is optional.
-o value --connection-timeout=value

The maximum time (in seconds) a connection can stay idle in the connection pool before being closed and discarded. This argument is optional.
-i value --min-connections=value

The minimum number of connections to keep in the connection pool. This argument is optional.
-a value --max-connections=value

The maximum number of connections to keep in the connection pool. This argument is optional.
-p value --pooling-scheme=value

The connection pooling algorithm to be used. Valid values are: WAIT: The --max-connections parameter will be strictly respected DYNAMIC: The number of connections may occasionally exceed the configured maximum number This argument is optional.
-q value

An SQL query that should be run directly after a connection has been created. This argument is optional.
-Ckey=value

A JDBC connection property that will be added to the existing list of connection properties. Several properties may be specified. This argument is optional and may be specified multiple times with different keys.
-e <true|false> --clear-connection-properties=<true|false>

If this flag is set the existing list of connection properties will be cleared. This argument is optional. The default value is false. EXAMPLES Setting the maximum number of connections in the pool:
modifydbconfig maxconnections=100

Setting the pooling scheme:

TIBCO Spotfire Server 5.5 245 (276)

modifydbconfig poolingscheme=WAIT

Setting the size of the statement pool of the DataDirect driver:

modifydbconfig CMaxPooledStatements=20

modify-ds-template
Modifies a data source template. SYNOPSIS
modify-ds-template [-c value | --configuration=value] [-b value | --bootstrap-config=value] <-n value | --name=value> [-e <true|false> | --enable=<true|false>] [-r value | --rename=value] [-d value | --definition=value]

OVERVIEW This command is used to modify a data source template used by Information Services. OPTIONS
-c value --configuration=value

The path to the server configuration file. This argument is optional. The default value is configuration.xml.
-b value --bootstrap-config=value

The path to the bootstrap configuration file. Refer to bootstrap.xml on page 158. This argument is optional.
-n value --name=value

The name of the data source template to modify. This argument is mandatory.
-e <true|false> --enable=<true|false>

The enable flag indicates whether or not the data source template should be enabled. If no argument is given the value will be unchanged. This argument is optional.
-r value --rename=value

The name to rename the data source template to. If no argument is given the value will be unchanged. This argument is optional.
-d value --definition=value

The path to the file to containing a new data source template definition. If no argument is given the value will be unchanged. This argument is optional.

246 (276)

TIBCO Spotfire Server 5.5

promote-admin
Assigns full administrator privileges to a user. SYNOPSIS
promote-admin [-b value | --bootstrap-config=value] [-t value | --tool-password=value] <-u value | --username=value>

OVERVIEW This command is used to promote a user to administrator by making the user account a member of the Administrator group. OPTIONS
-b value --bootstrap-config=value

The path to the bootstrap configuration file. Refer to bootstrap.xml on page 158. This argument is optional.
-t value --tool-password=value

The configuration tool password used to decrypt the database password in the bootstrap.xml file. If the tool password is omitted, the command will prompt the end-user for it on the console. Refer to bootstrap.xml on page 158. This argument is optional.
-u value --username=value

The name of the user to be promoted to administrator. Unless the user is part of the configured default domain, the name of the user needs to include the user's domain name, like DOMAIN\user or user@domain. This argument is mandatory.

remove-ds-template
Removes a data source template. SYNOPSIS
remove-ds-template [-c value | --configuration=value] [-b value | --bootstrap-config=value] <-n value | --name=value>

OVERVIEW This command is used to remove a data source template. OPTIONS

-c value --configuration=value

The path to the server configuration file. This argument is optional. The default value is configuration.xml.

TIBCO Spotfire Server 5.5

247 (276)

-b value --bootstrap-config=value

The path to the bootstrap configuration file. Refer to bootstrap.xml on page 158. This argument is optional.
-n value --name=value

The name of the data source template to remove. This argument is mandatory.

remove-jaas-config
Removes the specified JAAS application configurations from the server configuration. SYNOPSIS
remove-jaas-config [-c value | --configuration=value] [-b value | --bootstrap-config=value] <-n value | --name=value>

OVERVIEW This command is used to remove JAAS application configurations from the server. OPTIONS
-c value --configuration=value

The path to the server configuration file. This argument is optional. The default value is configuration.xml.
-b value --bootstrap-config=value

The path to the bootstrap configuration file. Refer to bootstrap.xml on page 158. This argument is optional.
-n value --name=value

The names of the JAAS application configurations to be removed from the server. Multiple names must be comma-separated and enclosed between quotes. This argument is mandatory.

remove-ldap-config
Removes LDAP configurations. SYNOPSIS
remove-ldap-config [-c value | --configuration=value] [-b value | --bootstrap-config=value] <LDAP configuration ids>

OVERVIEW This command can be used to remove LDAP configurations.

248 (276)

TIBCO Spotfire Server 5.5

OPTIONS
-c value --configuration=value

The path to the server configuration file. This argument is optional. The default value is configuration.xml.
-b value --bootstrap-config=value

The path to the bootstrap configuration file. Refer to bootstrap.xml on page 158. This argument is optional.
<LDAP configuration ids>

Specifies a comma-separated list of identifiers of the LDAP configurations to be removed. This argument is mandatory.

run
Runs a configuration script. SYNOPSIS
run <script file>

OVERVIEW This command is used to run a configuration script. OPTIONS

<script file>

The name of the script to be executed. This argument is mandatory. SCRIPT SYNTAX Each line must contain the name of a command and its arguments. Arguments may be quoted using either single or double quotes. Lines beginning with a hash character (#) are regarded as comments and have no effect. Lines ending with a backslash character (\) are continued on the next line with the backslash character removed before parsing. The special script command "echo" may be used to echo messages to the console. See Script Language on page 50.

set-auth-mode
Sets the authentication mode. Note: This command is deprecated from 5.0 and is replaced by the config-auth on page 186 command. SYNOPSIS
set-auth-mode [-c value | --configuration=value] [-b value | --bootstrap-config=value] <-a value | --auth-method=value> [-d |
TIBCO Spotfire Server 5.5 249 (276)

--jaas-database] [-l | --jaas-ldap] [-w | --jaas-windows] [-j value | --jaas-custom=value]

OVERVIEW This command is used to set the authentication mode. OPTIONS

-c value --configuration=value

The path to the server configuration file. This argument is optional. The default value is configuration.xml.
-b value --bootstrap-config=value

The path to the bootstrap configuration file. Refer to bootstrap.xml on page 158. This argument is optional.
-a value --auth-method=value

The authentication method to use. The following methods are supported: BASIC, CLIENT_CERT, NTLM, Kerberos and Delegate. The names may be specified in either upper or lower case. This argument is mandatory.
-d --jaas-database

Use the Spotfire database authentication source, as configured in the SpotfireDBLogin JAAS application configuration. This option is only permitted when using the BASIC authentication method. It is also mutually exclusive with all other options related to BASIC authentication sources. This argument is optional.
-l --jaas-ldap

Use the LDAP authentication source, as configured in the SpotfireLDAP JAAS application configuration. This option is only permitted when using the BASIC authentication method. It is also mutually exclusive with all other options related to BASIC authentication sources. This argument is optional.
-w --jaas-windows

Use the Windows NT authentication source, as configured in the SpotfireWindows JAAS application configuration. This option is only permitted when using the BASIC authentication method. It is also mutually exclusive with all other options related to BASIC authentication sources. This argument is optional.
-j value --jaas-custom=value

Use the custom JAAS application configuration with the specified name. This option is only permitted when using the BASIC authentication method. It is also mutually exclusive with all other options related to BASIC authentication sources. This argument is optional.

250 (276)

TIBCO Spotfire Server 5.5

set-config
Sets the current server configuration. SYNOPSIS
set-config [-b value | --bootstrap-config=value] [-t value | --tool-password=value] <-h value | --hash=value> <-c value | --comment=value>

OVERVIEW This command is used to set the current configuration to one of the existing configurations. Refer to list-configs on page 234. OPTIONS
-b value --bootstrap-config=value

The path to the bootstrap configuration file. Refer to bootstrap.xml on page 158. This argument is optional.
-t value --tool-password=value

The configuration tool password used to decrypt the database password in the bootstrap.xml file. If the tool password is omitted, the command will prompt the end-user for it on the console. Refer to bootstrap.xml on page 158. This argument is optional.
-h value --hash=value

The (possibly abbreviated) hash of the configuration to set. Must be at least the first six hexadecimal characters of the hash. This argument is mandatory.
-c value --comment=value

A comment describing the reason for the configuration change. This argument is mandatory.

set-db-config
Sets the common database connection configuration. SYNOPSIS
set-db-config [-c value | --configuration=value] [-b value | --bootstrap-config=value] [-l value | --login-timeout=value] [-o value | --connection-timeout=value] [-i value | --min-connections= value] [-a value | --max-connections=value] [-p value | --pooling-scheme=value] [-q value] {-Ckey=value}

TIBCO Spotfire Server 5.5

251 (276)

OVERVIEW This command is used to set the common configuration for the connection to the Spotfire Server database. This configuration (which effects all servers) will be merged with the configuration in the bootstrap.xml file on each server. OPTIONS
-c value --configuration=value

The path to the server configuration file. This argument is optional. The default value is configuration.xml.
-b value --bootstrap-config=value

The path to the bootstrap configuration file. Refer to bootstrap.xml on page 158. This argument is optional.
-l value --login-timeout=value

The maximum time (in seconds) to wait for a connection to become available. This argument is optional. The default value is 10.
-o value --connection-timeout=value

The maximum time (in seconds) a connection can stay idle in the connection pool before being closed and discarded. This argument is optional. The default value is 600.
-i value --min-connections=value

The minimum number of connections to keep in the connection pool. This argument is optional. The default value is 5.
-a value --max-connections=value

The maximum number of connections to keep in the connection pool. This argument is optional. The default value is 40.
-p value --pooling-scheme=value

The connection pooling algorithm to be used. Valid values are: WAIT: The --max-connections parameter will be strictly respected DYNAMIC: The number of connections may occasionally exceed the configured maximum number. This argument is optional. The default value is WAIT.
-q value

An SQL query that should be run directly after a connection has been created. This argument is optional.
-Ckey=value

A JDBC connection property. Several properties may be specified. This argument is optional and may be specified multiple times with different keys.

252 (276)

TIBCO Spotfire Server 5.5

EXAMPLES Example of how to set the maximum number of connections in the pool:
setdbconfig maxconnections=100

Example of how to set the pooling scheme:

setdbconfig poolingscheme=WAIT

Example of how to set the size of the statement pool of the DataDirect driver:
setdbconfig CMaxPooledStatements=20

set-restart-policy
Sets the server restart policy. SYNOPSIS
set-restart-policy [-c value | --configuration=value] [-b value | --bootstrap-config=value] <-p value | --policy=value>

OVERVIEW This command is used to set the way the server(s) react to configuration changes. Each server periodically checks for configuration changes and handles any such changes according to the policy set using this command. OPTIONS
-c value --configuration=value

The path to the server configuration file. This argument is optional. The default value is configuration.xml.
-b value --bootstrap-config=value

The path to the bootstrap configuration file. Refer to bootstrap.xml on page 158. This argument is optional.
-p value --policy=value

Controls whether the server(s) should be restarted when a configuration change is detected, and if so when. Valid values are: MANUAL: The changes wont have any effect until the server(s) are manually restarted AUTOMATIC_FORCE: The server(s) are immediately automatically restarted AUTOMATIC_ON_IDLE: The server(s) are automatically restarted when considered idle Note that the AUTOMATIC_FORCE option may result in currently running user operations being aborted. This argument is mandatory.

TIBCO Spotfire Server 5.5

253 (276)

set-userdir-mode
Sets the User Directory mode. Note: This command is deprecated from 5.0 and is replaced by the config-userdir on page 205 command. SYNOPSIS
set-userdir-mode [-c value | --configuration=value] [-b value | --bootstrap-config=value] <-m value | --mode=value>

OVERVIEW This command is used to set the User Directory mode. OPTIONS
-c value --configuration=value

The path to the server configuration file. This argument is optional. The default value is configuration.xml.
-b value --bootstrap-config=value

The path to the bootstrap configuration file. Refer to bootstrap.xml on page 158. This argument is optional.
-m value --mode=value

The name of the User Directory mode to use. Supported values are database, ldap and windows. This argument is mandatory.

show-basic-ldap-auth
Shows the LDAP authentication source for use with the BASIC authentication method. SYNOPSIS
show-basic-ldap-auth [-c value | --configuration=value] [-b value | --bootstrap-config=value]

OVERVIEW This command is used to show the LDAP authentication source(s) for use with the BASIC authentication method. The configuration is stored within the SpotfireLDAP JAAS application configuration. OPTIONS The arguments are as follows:

254 (276)

TIBCO Spotfire Server 5.5

-c value --configuration=value

The path to the server configuration file. This argument is optional. The default value is configuration.xml.
-b value --bootstrap-config=value

The path to the bootstrap configuration file. See the bootstrap.xml help topic for more information about this file. This argument is optional.

show-config-history
Shows the configuration history. SYNOPSIS
show-config-history [-b value | --bootstrap-config=value] [-t value | --tool-password=value] [-h value | --hash-abbrev=value]

OVERVIEW This command is used to show the configuration history. The most recent entry is the current configuration. OPTIONS
-b value --bootstrap-config=value

The path to the bootstrap configuration file. Refer to bootstrap.xml on page 158. This argument is optional.
-t value --tool-password=value

The configuration tool password used to decrypt the database password in the boot strap.xml file. If the tool password is omitted, the command will prompt the end-user for it on the console. Refer to bootstrap.xml on page 158. This argument is optional.
-h value --hash-abbrev=value

The number of hexadecimal digits to abbreviate the configuration hash to. Must be a number between 6 and 40. This argument is optional. The default value is 7.

show-deployment
Shows the current deployment. SYNOPSIS
show-deployment [-b value | --bootstrap-config=value] [-t value | --tool-password=value] [-a value | --area=value] [-s | --show-ids]

TIBCO Spotfire Server 5.5

255 (276)

OVERVIEW This command is used to show the current deployment in a given area. OPTIONS The arguments are as follows:
-b value --bootstrap-config=value

The path to the bootstrap configuration file. See the bootstrap.xml help topic for more information about this file. This argument is optional.
-t value --tool-password=value

The configuration tool password used to decrypt the database password in the bootstrap.xml file. If the tool password is omitted, the command will prompt the end-user for it on the console. See the bootstrap.xml help topic for more information. This argument is optional.
-a value --area=value

The deployment area for which to show the current deployment. This argument is optional. The default value is production.
-s --show-ids

This flag can be used to indicate that the package IDs should be included in the output. A package ID is needed to remove a specific package using the update-deployment on page 260 command. This argument is optional.

show-import-export-directory
Shows the library import/export directory. SYNOPSIS
show-import-export-directory [-c value | --configuration=value] [-b value | --bootstrap-config=value]

OVERVIEW This command is used to show the library import/export directory. All library import and export operations will be done from/to this directory which may be a local directory of reside on a shared disk. OPTIONS The arguments are as follows:
-c value --configuration=value

The path to the server configuration file. This argument is optional. The default value is configuration.xml.
256 (276) TIBCO Spotfire Server 5.5

-b value --bootstrap-config=value

The path to the bootstrap configuration file. See the bootstrap.xml help topic for more information about this file. This argument is optional.

show-join-database
Shows the configured default join database. SYNOPSIS
show-join-database [-c value | --configuration=value] [-b value | --bootstrap-config=value]

OVERVIEW This command can be used to show the configured default join database, used by Information Services. OPTIONS The arguments are as follows:
-c value --configuration=value

The path to the server configuration file. This argument is optional. The default value is configuration.xml.
-b value --bootstrap-config=value

The path to the bootstrap configuration file. See the bootstrap.xml help topic for more information about this file. This argument is optional.

show-restart-policy
Shows the server restart policy. SYNOPSIS
show-restart-policy [-c value | --configuration=value] [-b value | --bootstrap-config=value]

OVERVIEW This command shows the restart policy. Valid values are: MANUAL (the changes wont have any effect until the server(s) are manually restarted), AUTOMATIC_FORCE (the server(s) are immediately automatically restarted) and AUTOMATIC_ON_IDLE (the server(s) are automatically restarted when considered idle). Note that the AUTOMATIC_FORCE option may result in currently running user operations being aborted.

TIBCO Spotfire Server 5.5

257 (276)

OPTIONS The arguments are as follows:

-c value --configuration=value

The path to the server configuration file. This argument is optional. The default value is configuration.xml.
-b value --bootstrap-config=value

The path to the bootstrap configuration file. See the bootstrap.xml help topic for more information about this file. This argument is optional.

switch-domain-name-style
Switches the domain names for all users and groups from one style (DNS or NetBIOS) to the other (for all configured domains). SYNOPSIS
switch-domain-name-style [-b value | --bootstrap-config=value] [-t value | --tool-password=value] <-n value | --new-domain-name-style= value>

OVERVIEW This command may be used to switch the domain names for all existing users and groups from one style (DNS or NetBIOS) to the other (for all configured domains). The new domain name style must first be configured using the configuserdir command. Note that this command is only applicable when using a User Directory in LDAP mode against Active Directory. OPTIONS The arguments are as follows:
-b value --bootstrap-config=value

The path to the bootstrap configuration file. See the 'bootstrap.xml' help topic for more information about this file. This argument is optional.
-t value --tool-password=value

The configuration tool password used to decrypt the database password in the bootstrap.xml file. If the tool password is omitted, the command will prompt the end-user for it on the console. See the 'bootstrap.xml' help topic for more information. This argument is optional.
-n value --new-domain-name-style=value

The new domain name style. Valid values are dns and netbios. This argument is mandatory.

258 (276)

TIBCO Spotfire Server 5.5

test-jaas-config
Tests a JAAS application configuration. SYNOPSIS
test-jaas-config [-b value | --bootstrap-config=value] [-t value | --tool-password=value] [-c value | --configuration=value] <-j value | --jaas-configuration=value> <-u value | --username=value> [-p value | --password=value]

OVERVIEW This command is used to test a JAAS application configuration by performing a login attempt, using the specified credentials. It can test either a configuration stored in the server database or a configuration stored in an exported configuration file. To test a configuration stored in a configuration file, use the configuration argument. Otherwise the configuration stored in the database will be tested. If the JAAS login module requires a connection to the server database, the configuration argument cannot be used. OPTIONS
-b value --bootstrap-config=value

The path to the bootstrap configuration file. Refer to bootstrap.xml on page 158. This argument is optional.
-t value --tool-password=value

The configuration tool password used to decrypt the database password in the bootstrap.xml file. If the tool password is omitted, the command will prompt the end-user for it on the console. Refer to bootstrap.xml on page 158. This argument is optional.
-c value --configuration=value

The path to an exported server configuration file. If this parameter is omitted, the application will attempt to retrieve the configuration parameters from the server database, using the bootstrap.xml file specified by the bootstrap argument. This argument is optional.
-j value --jaas-configuration=value

The name of the JAAS application configuration to test. This argument is mandatory.
-u value --username=value

The name of the user to login as. This argument is mandatory.

-p value --password=value

The password of the user to login as. If the password is omitted, the command will prompt the end-user for it on the console. This argument is optional.

TIBCO Spotfire Server 5.5

259 (276)

update-deployment
Updates the current deployment. SYNOPSIS
update-deployment [-b value | --bootstrap-config=value] [-t value | --tool-password=value] <-a value | --area=value> [-c | --clear] [-r value | --remove-packages=value] [-v value | --version=value] [-d value | --description=value] [-f | --force-update] [deployment files]

OVERVIEW This command is used to add a new deployment or to update the current deployment in a given area. OPTIONS The arguments are as follows:
-b value --bootstrap-config=value

The path to the bootstrap configuration file. See the bootstrap.xml help topic for more information about this file. This argument is optional.
-t value --tool-password=value

The configuration tool password used to decrypt the database password in the boot strap.xml file. If the tool password is omitted, the command will prompt the end-user for it on the console. See the bootstrap.xml help topic for more information. This argument is optional.
-a value --area=value

The deployment area which should be updated. This argument is mandatory.

-c --clear

This flag may be used to indicate that all existing packages should be removed before any new files are added. If no files to add to the deployment are provided the deployment area will become empty. This argument is optional.
-r value --remove-packages=value

A comma separated list of IDs of packages that should be removed from the deployment. The IDs can be determined using the 'show-deployment' command. Should not be specified together with the clear flag.
-v value --version=value

The version of the new deployment. If no value is given it is taken from the current deployment, or from the last added distribution if one is added. This argument is optional.

260 (276)

TIBCO Spotfire Server 5.5

-d value --description=value

The description of the new deployment. If no value is given it is taken from the current deployment, or from the last added distribution if one is added. This argument is optional.
-f --force-update

This flag may be used to indicate that users connecting to the server should be forced to update their clients. This argument is optional.
[deployment files]

A comma separated list of files (packages and distributions) that should be added to the deployment. Note that the paths cannot contain spaces. This argument is optional.

update-ldap-config
Updates LDAP configurations. SYNOPSIS
update-ldap-config [-c value | --configuration=value] [-b value | --bootstrap-config=value] <--id=value> [-t value | --type=value] [-s value | --servers=value] [--clear-context-names] [-n value | --context-names=value] [-u value | --username=value] [-p value | --password=value] [--schedules=value] [--clear-schedules] [--user-search-filter=value] [--user-name-attribute=value] [--authentication-attribute=value] [--security-authentication=value] [--referral-mode=value] [--request-control=value] [--page-size=value] [--import-limit=value] [--user-display-name-attribute=value] [--group-display-name-attribute=value] {-Ckey=value}

OVERVIEW This command can be used to update LDAP configurations. OPTIONS

-c value --configuration=value

The path to the server configuration file. This argument is optional. The default value is configuration.xml.
-b value --bootstrap-config=value

The path to the bootstrap configuration file. Refer to bootstrap.xml on page 158. This argument is optional.
--id=value

Specifies the identifier for the LDAP configuration to be updated. This argument is mandatory.
-t value --type=value

The type of LDAP server. The following names are valid types:
TIBCO Spotfire Server 5.5 261 (276)

ActiveDirectory SunOne SunJavaSystem Custom When specifying any of the first three types, a type-specific configuration template is automatically applied in runtime, so that the most fundamental configuration options are automatically configured. When specifying a Custom LDAP server type, there is no such configuration template and all those configuration options must be specified explicitly. When a custom LDAP configuration is to be used for authentication or with the User Directory LDAP provider, the usersearchfilter and usernameattribute arguments must be specified. For such an LDAP configuration to be used for group synchronization, additional parameters must also be specified when running the configldapgroupsync command.

-s value --servers=value

This argument is used to specify a whitespace-separated list of LDAP server URLs. An LDAP server URL has the format <protocol>://<server>[:<port>]: <protocol>: Either LDAP or LDAPS <server>: The fully qualified DNS name of the LDAP server. <port>: Optional. Number indicating the port number the LDAP service is listening on. When using the LDAP protocol, the port number defaults to 389. When using the LDAPS protocol, the port number defaults to 636. Active Directory LDAP servers also provides a Global Catalog containing forest-wide information, instead of domain-wide information only. The Global Catalog LDAP service by default listens on port number 3268 (LDAP) or 3269 (LDAPS). The Spotfire Server does not expect any search base, scope, filter or other additional parameters after the port number in the LDAP server URLs. Such properties are specified using other configuration options for this command. Unless the discover option is used, this argument is mandatory. Examples: LDAP server URL
LDAP://myserver.example.com LDAPS://myserver.example.com LDAP://myserver.example.com:389 LDAPS://myserver.example.com:636 LDAP://myserver.example.com:3268 LDAPS://myserver.example.com:3269
--clear-context-names

By specifying this flag, the context names are cleared from the LDAP configuration. This flag can be used together with the contextnames flag to remove all old context names before adding the new. This argument is optional.
-n value --context-names=value

A list of distinguished names (DNs) of containers holding LDAP accounts to be visible within the Spotfire Server. When specifying more than one DN, then the DNs must
262 (276) TIBCO Spotfire Server 5.5

be separated by pipe-characters (|). The specified context names are added to the context names that are already configured. To set the context names from scratch, use the clearcontextnames argument with the contextnames. This argument is optional. If the specified containers contain a large number of users, of which only a few should be visible in the Spotfire Server, a custom user search filter can be specified to include only the designated users (see the usersearchfilter argument). Examples:
CN=users,DC=example,DC=com OU=projectx,DC=research,DC=example,DC=com
-u value --username=value

The name of the LDAP service account to be used when searching for users (and optionally also groups) in the LDAP server. This service account does not need to have any write permissions, but it needs to have read permissions for all configured context names (LDAP containers). For most LDAP servers, the account name is the accounts distinguished name (DN). For Active Directory, the account name can also be specified in the forms ntdomain\name and name@dnsdomain. This argument is optional. Examples:
CN=spotsvc,OU=services,DC=research,DC=example,dc=COM RESEARCH\spotsvc (Active Directory only) [email protected] (Active Directory only)
--password=value

The password for the LDAP service account. This argument is optional.
--schedules=value

A comma-separated list of schedules for when the LDAP synchronization should be performed. The schedules are given in a cron-compatible format, where each schedule consists of either five fields or one shorthand label. Please make sure to enclose the value in double quotes. The specified schedules are added to the schedules that are already configured. To set the schedules from scratch, use the clearschedules argument with the schedules. This argument is optional. The five fields are, from left to right, with their valid ranges: minute (0-59), hour (0-23), day of month (1-31), month (1-12) and day of week (0-7, where both 0 and 7 indicate Sunday). A field may also be configured with the wildcard character *, indicating that any moment in time matches this field. A group synchronization is triggered when all fields match the current time. If both day of month and day of week have non-wildcard values, then only one of them has to match. There are also the following shorthand labels that can be used instead of the full cron expressions:
@yearlyor@annually:runonceayear(equivalentto0011*) @monthly:runonceamonth(equivalentto001**) @weekly:runonceaweek(equivalentto00**0) @dailyor@midnight:runonceaday(equivalentto00***)

TIBCO Spotfire Server 5.5

263 (276)

@hourly:runonceanhour(equivalentto0****) @minutely:runonceaminute(equivalentto*****) @rebootor@restart:runeverytimetheSpotfireServerisstarted

Refer to the Wikipedia overview article on the cron scheduler.

--clear-schedules

By specifying this flag, the LDAP synchronization schedules are cleared from the LDAP configuration. This flag can be used together with the --schedules flag to remove all old schedules before adding the new. This argument is optional.
--user-search-filter=value

This parameter specifies an LDAP search expression filter to be used when searching for users. The parameter is mandatory for all custom configurations.

For Active Directory servers, the parameter value defaults to objectClass=user. For any version of the Sun Directory Servers, it defaults to objectClass=person.

This argument is optional, but it must be specified for custom LDAP configurations, either when running this command or the createldapconfig command. If only a subset of all the users in the specified LDAP containers should be allowed access to the Spotfire Server, a more detailed user search filter can be used. The search expression can for instance be expanded so that it also puts restrictions on which groups the users belong to, or which roles they have.

For Active Directory servers, access can be restricted to only those users belonging to a certain group by using a search expression with the pattern &(objectClass=user)(memberOf=<groupDN>), where <groupDN> is to be replaced by the real DN of the group to which the users must belong. If the users are divided among multiple groups, use the pattern &(objectClass=user)(|(memberOf= <firstDN>)(memberOf=<secondDN>)). Add extra (memberOf=<groupDN>) sub-expressions as needed. Active Directory Example:
&(objectClass=person)(isMemberOf=cn=projectx,dc=example,dc=com)

For a Sun Java System Directory Server version 6 and later, the same effect as above can be achieved by using a search expression with the pattern &(objectClass=person)(isMemberOf=<groupDN>). If the users are divided among multiple groups, use the pattern &(objectClass=person)(|(isMemberOf= <firstDN>)(isMemberOf=<secondDN>)). Add extra (isMemberOf=<groupDN>) sub-expressions as needed. Sun Java System Directory Server Example:
&(objectClass=person)(isMemberOf=cn=projectx,dc=example,dc=com)

For Sun ONE Directory Servers as well as the newer Sun Java System Directory Servers or the older iPlanet Directory Server, access can be restricted to only those users having certain specific roles. The search expression for role filtering must match the pattern &(objectClass=person)(nsRole=<roleDN>). If multiple roles are of interest, use the pattern &(objectClass=person)(|(nsRole=<firstDN>)(nsRole= <secondDN>). Add extra (nsRole=<roleDN>) sub-expressions as needed.

264 (276)

TIBCO Spotfire Server 5.5

Sun ONE Directory Servers Example: &(objectClass=person)(isMemberOf=cn=

projectx,dc=example,dc=com)

The syntax of LDAP search expression filters is specified by the RFC 4515 document. Please consult this documentation for information about more advanced filters.
--user-name-attribute=value

Specifies the name of the LDAP attribute containing the user account names. For Active Directory servers the value defaults to sAMAccountName. For a Sun Java System Directory Server (or any older Sun ONE Directory Server or iPlanet Directory Server) with a default configuration, it defaults to uid. This argument is optional, but it must be specified for custom LDAP configurations, either when running this command or the createldapconfig command.
--authentication-attribute=value

Specifies the name of the LDAP attribute containing a user identity that can be used for binding (authenticating) to the LDAP server. This attribute fills no purpose in most common LDAP configurations, but can be useful in more advanced setups, where the distinguished name (DN) does not work for authentication or where users should be able to login using a username which does not map directly to an actual LDAP account. When setting up SASL with DIGEST-MD5 in an Active Directory environment, the DN does not work for authentication and the userPrincipalName attribute must be used instead. The authenticationattribute argument should then be set to userPrincipal Name and the usernameattribute argument should be set to sAMAccountName (the latter value also happens to be the default value for an Active Directory LDAP configuration, so there's no need to set it explicitly). See also the securityauthentication argument. When setting up SASL with GSSAPI in an Active Directory environment, the DN does not work for authentication and the sAMAccountName or userPrincipalName attribute must be used instead. The authenticationattribute argument should then be set to sAMAccountName or userPrincipalName and the username attribute argument should be set to sAMAccountName (the latter value also happens to be the default value for an Active Directory LDAP configuration, so there is no need to set it explicitly). See also the securityauthentication argument. Example:

By setting the usernameattribute argument to cn and the authenticationattribute argument to userPrincipalName in an Active Directory environment, the end-users will be able to login to the Spotfire Server using their CN attribute values, but underneath the hood, the Spotfire Server will actually use the userPrincipalName attribute value of the LDAP account with the matching CN for the actual authentication.

This argument is optional and should only be used in advanced setups. It is not set by default.
--security-authentication=value

This parameter specifies the security level to use when binding to the LDAP server. To enable anonymous binding, it should be set to none.

TIBCO Spotfire Server 5.5

265 (276)

To enable plain username/password authentication, it should be set to simple. To enable SASL authentication, it should be set to the name of the SASL mechanism to be used, for instance DIGESTMD5 or GSSAPI. Use multiple C flags to set the additional JNDI environment properties that the SASL authentication mechanism typically requires.

When setting up SASL with DIGEST-MD5 in an Active Directory environment, all accounts must use reversible encryption for their passwords. This is typically not the default setting for the domain controller. The authenticationattribute argument must also be used to specify the userPrincipalName attribute for the actual authentication to work correctly. When setting up SASL with GSSAPI in an Active Directory environment, the authenticationattribute argument must be used to specify either the sAMAccount Name or the userPrincipalName attribute and the custom property kerberos.login.con text.name must be mapped to the JAAS application configuration SpotfireGSSAPI. This in turn requires a fully working Kerberos configuration file at <installationdirectory>/ jdk/jre/lib/security/krb5.conf. This argument is optional and should only be used in advanced setups. The default value is simple.
--referral-mode=value

This argument specifies how LDAP referrals should be handled. Valid arguments are follow (automatically follow any referrals), ignore (ignore referrals) and throw (fail with an error). The default and recommended value is follow. This argument is optional.
--request-control=value

This argument determines the type of LDAP controls to be used when executing search queries to the LDAP server. The default behavior is to probe the LDAP server for the best supported request control. The paged results control is always preferred, since it provides the most efficient way of retrieving the querys result set. The virtual list view control can also be used for the same purpose if the paged results control is not supported. The virtual list view control will automatically be used together with a sort control. Both the paged results control and the virtual list view control supports a configurable page size, set by the pagesize argument.

To explicitly configure the server for probing, set the argument value to probe. To configure the server for the paged results control, set the argument value to PagedResultsControl. To request the virtual list view control, set the argument value to VirtualListViewControl. To completely disable request controls by setting the argument value to none.

This argument is optional. The default value is probe.

--page-size=value

This argument specifies the page size to be used with the paged results control or the virtual list view control when performing search queries to the LDAP server. The page size value defaults to 2000 for both the paged results control and the virtual list view control. This argument is optional.
266 (276) TIBCO Spotfire Server 5.5

--import-limit=value

This argument specifies a threshold that limits the number of users that can be imported from an LDAP server to the Spotfire Server in one query. This can be used to prevent accidental flooding of the Spotfire Servers User Directory when integrating with an LDAP server with tens or even hundreds of thousands of users. By setting an import limit, the administrator can be sure that an unexpected high number of users wont affect the servers performance. By default, there is no import limit. To explicitly request unlimited import, set the parameter value to 1. All positive numbers are treated as an import limit. In most cases, it is recommended to leave this parameter untouched. This argument is optional.
--user-display-name-attribute=value

Specifies the name of the LDAP attribute containing the user display names. This argument is optional.
--group-display-name-attribute=value

Specifies the name of the LDAP attribute containing the group display names. This argument is optional.
-Ckey=value

This argument specifies additional JNDI environment properties to be used when connecting to the LDAP server. This argument is optional and may be specified multiple times with different keys. Please note that it does not add to the previously configured custom properties, it replaces them completely. If you want to keep any of the old custom properties, make sure to specify them once again when adding new ones. Example: The equivalent of specifying the securityauthentication=DIGESTMD5 argument is -Cjava.naming.security.authentication=DIGEST-MD5 Example: Updating the context names
updateldapconfigid="ldap1"contextnames="OU=projectx,DC=research,DC= example,DC=com|OU=phbs,DC=management,DC=example,DC=com"

version
Displays the current version of the server. SYNOPSIS
version

OVERVIEW This command is used to display the current version of the server.

TIBCO Spotfire Server 5.5

267 (276)

Reference:Troubleshooting
Spotfire Server Logs
Logs store the important diagnostic information about the Spotfire Server that can help in troubleshooting and resolving issues. Spotfire server, by default runs at the minimal logging level and this can be elevated, when needed. The most important log is the "server.log" (previously named as dss.log in 3.x versions). This log file stores information about all activities on the server and can be very handy in troubleshooting issues. Note: If there is any issue with Spotfire Server, provide the server logs to Spotfire Support when logging the support request. Here is a list of logs that are available with Spotfire Server, categorized based on what they capture:
Log Name File Name Contents

Configuration Tool Log tools.log

This log file stores information about activity of the configuration tool / Configuration Command Line Tool. For example, if you run any configuration commands at the command prompt or use the UI, this is the log that captures that information. Information about all activity on the server except those events recorded in the Server Access Log. Information about client access and access attempts to the server and files in the library. Information about client access and access attempts to the server. Information about Spotfire Library usage. Information about Spotfire Library imports and exports. Information about Information Services usage.

Server Log

server.log

Server Access Log

access.log

Server Usage Log Library Log Library Import/Export Log Information Services Usage Log

usage.log library.log impex.log isusage.log

268 (276)

TIBCO Spotfire Server 5.5

SQL Log

sql.log

Information about executed SQL queries performed when an information link is executed. Information about SOAP communication. Diagnostic information about server measures. Information about JAR files loaded on server startup.

SOAP Log

soap.log

Server Diagnostics Log server-diagnostics.log

Startup Log

startup.log

Different logging levels that can be used for Server logs: Spotfire Server runs by default at Info (log4j.properties) logging level. This logging level can be elevated to capture more information about issues, errors etc. There are two methods of changing the logging level: 1 2 When Spotfire Server is up and running - using the Open Logs and Diagnostics tab from Spotfire Server > Welcome Page. When Spotfire Server is not running - by modifying the com.spotfire.logging.config.file parameter in web.xml file located under <SpotfireServer InstallDir.>\tomcat\webapps\spotfire\WEBINF\ folder Note: Though elevated logging is good for troubleshooting, run Spotfire Server in Info (log4j.properties) logging mode when server is running fine. Note: Though there are quite a few logging methods that can be used in Spotfire, these are the most commonly used methods for troubleshooting Spotfire server issues. log4j.properties: This is the default log level set in Spotfire Server and captures the events in Info mode. log4j-debug.properties: When this log level is set, the Server Log (server.log) logs detailed debug information as well as warnings, errors and other information. And the SQL Log (sql.log) logs detailed SQL information. If the server is started from a command prompt or shell, the output to the command prompt or shell is also be included in the Server Log. log4j-trace.properties: This log4j level gives more detailed information than the DEBUG level and should be used only when needed. Note that this logging level is very verbose and running Spotfire Server.

TIBCO Spotfire Server 5.5

269 (276)

Location of server logs:

Location of Spotfire Server Log files:

Spotfire Server logs are located under <SpotfireServerInstallDir.>\tomcat\logs folder. Example: C:\tibco\tss\5.5.0\tomcat\logs Spotfire Server Upgrade logs are located under <SpotfireServerInstallDir.>\ Example: C:\tibco\tss\5.5.0\tools\upgrade\logs

Location of Upgrade Log files:

tools\upgrade\logs folder

Note: Logs default directory location can be changed by modifying the following parameter in the <SpotfireServerInstallDir.>\tomcat\webapps\spotfire\ WEBINF\web.xml file

<context-param> <param-name>log.dir</param-name> <param-value>/../../logs</param-value> </context-param>

Enabling debug logging on Spotfire Server: When Spotfire Server is up and running: 1 2 3 4 5 Launch Spotfire Administration Console by using Spotfire Server URL in a Web browser Click Open Logs and Diagnostics. Login using Administrator credentials and click on Server Log Files tab. Select the required log from the dropdown menu to the left and set the required logging level using the dropdown menu to the right on the screen. Click Refresh to see the latest entries in the log. Note: Enabling debug logging from this console does not need a server restart. Note: To export the log file from this console, click the Export Log File icon in the right upper corner. Note: Based on requirements, select a different logging level and a different log file using the various options in the dropdown menu options Note: Information under the Diagnostics tab provides useful diagnostic information about various aspects of Spotfire Server like Application Server, Database Server, Uptime etc.

270 (276)

TIBCO Spotfire Server 5.5

When Spotfire Server is not working: 1 2 Backup and open the web.xml file from <SpotfireServerInstallDir.>\tomcat\webapps\ spotfire\WEBINF folder in a text editor (for example Notepad). Find log4j.propertiesparameter in this file. An example on how this parameter looks like the web.xml file:

Replace it with log4jdebug.properties and save the file. Here is how the changed parameter should look like:

4 5

Save the file. Restart the "Spotfire Server Service" from "Windows Services" for the changes to take effect. Note: Always take a backup of the web.xml file before making any modifications Note: Use any text editor (for example Notepad) to modify the XML files. Do not use applications such as Wordpad which may change the file encoding and result in corrupted XML Fles. Note: Disable Debug logging once the troubleshooting is completed. It is not recommended to run the server in debug mode for longer periods. Note: It is a good practice to back up the existing logs and clear the logs folder before capturing the debug logs. Capturing Spotfire Server Diagnostics:

1 2 3 4

Launch Spotfire Administration Console by using Spotfire Server URL in a Web browser. Click on Open Logs and Diagnostics. Login using Administrator credentials and click the Diagnostics tab. Click Export to file and save the file. Enabling Kerberos Debug logging on Spotfire Server: If there are any issues with the Kerberos authentication, please follow the instructions below to enable Kerberos debug logging on Spotfire Server:

TIBCO Spotfire Server 5.5

271 (276)

1 2

Open the configuration.xml file from <SpotfireServerInstallDir.>\tomcat\bin folder in a text editor (ex: Notepad) Locate the following configuration block in the configuration.xml file:

Change the value for debug key from false to true.

4 5 6 7

Save the file. Launch a Command prompt on Spotfire Server and browse to the <SpotfireServer installDir.>\tomcat\bin folder. Import the configuration using importconfig command. For example: config
importconfigcomment="EnabledKerberosDebugLogging"

Open the web.xml file from <SpotfireServerInstallDir.>\tomcat\webapps\spotfire\ WEBINF\ folder in a text editor (for example Notepad).

272 (276)

TIBCO Spotfire Server 5.5

Find the log4j.properties parameter in this file. An example on how this parameter looks like the web.xml file:

Replace it with log4jdebug.properties and save the file. Here is how the changed parameter should look like:

10 11

Save the file. Restart the Spotfire Server Service from 'Windows Services for the changes to take effect. Note: Always take a backup of the web.xmlfile before making any modifications. Note: Use any text editor (for example Notepad) to modify the XML files. Do not use applications such as Wordpad which may change the file encoding and result in corrupted XML Files. Note: Disable Debug logging once the troubleshooting is completed. It is not recommended to run the server in debug mode for longer periods. Note: It is a good practice to back up the existing logs and clear the logs folder before capturing the debug logs.

Basic Troubleshooting steps

If there are any issues with Spotfire Server, here are a few aspects that needs to be checked: 1 Spotfire Database

Make sure Spotfire Server Database is up and running. Validate the Database credentials specified in the bootstrap.xml file.

Ensure the DB user has access to all the required Spotfire database Tables and Procedures i.e. if you login to Spotfire Server Database with those credentials, the user should be able to browse and access all the contents of Spotfire database.

Make sure there is communication between Spotfire Server machine and Spotfire database Server -Ex: Ping DB Server from Spotfire Server. Review the Spotfire Server logs for more clues.

Spotfire Server
273 (276)

TIBCO Spotfire Server 5.5

Make sure that Spotfire Server has network connectivity. Spotfire Server Service is up and running.

If a Custom User Account is used to run the Spotfire Server Service, ensure the account credentials are valid and not locked.

No port conflicts with the Spotfire Server ports. Spotfire Server Administration Console can be accessed outside the Spotfire Server machine.

If it works fine on the server machine but not accessible outside the server, make sure there is no Firewall or Proxy blocking the Server access.

If Spotfire Administration Console comes up but fails to authenticate, check the server logs for more clues.

Common Issues
1 Issue: Symptom: Spotfire Server may fail to start with the following error message: Error initializing the Spotfire web application. Please contact the server administrator and the following errors are captured in the server logs: ============ EVERE: Catalina.start: LifecycleException: service.getName(): "Spotfire"; Protocol handler start failed: java.net.BindException: Address already in use: JVM_Bind <null>: ============ Resolution: This is an indication of a Port conflict. You may check if any of the Spotfire Server ports are blocked by other processes on the Spotfire Server machine. Either stop those services so that Spotfire Server can grab these ports or assign a different port by modifying the server.xml file located under \tomcat\conffolder 2 Issue: Symptom: Spotfire Server may run out of JVM memory which may cause issues like Spotfire Server failure/hang, unable to allow any new connections or throw the following message when opening up any files: ============ Error message: Java heap space ============

274 (276)

TIBCO Spotfire Server 5.5

The following errors may be captured in the server logs: ============ Caused by: java.lang.OutOfMemoryError: GC overhead limit exceeded .. SEVERE: Exception invoking periodic operation: java.lang.OutOfMemoryError: Java heap space ============ Resolution: This exception is thrown by the garbage collector in the underlying Java and is not specific to Spotfire. This error essentially means that you need to add more memory. Refer to the 'Virtual Memory' settings in Spotfire Server installation manual for more information. Issue: Symptom: User's may not be able to login to Spotfire Professional or WebPlayer clients. Administrators may fail to login to Spotfire Administration Console. Server logs may indicate the following LDAP error code: ======= javax.naming.AuthenticationException: [LDAP: error code 49 - 80090308: LdapErr: DSID-0C090334, comment: AcceptSecurityContext error, data 52e, vece ] ========= Resolution: The LDAP error code indicates that the login credentials used for LDAP binding are invalid. One of the main reasons this can happen is if the password of the LDAP Service Account is expired. To resolve this issue, modify the LDAP configuration with the updated credentials. Issue: Symptom: User's may not be able to login to Spotfire Professional or WebPlayer clients. Administrators may fail to login to Spotfire Administration Console. Server logs may indicate the following LDAP error code: ======= javax.naming.AuthenticationException: [LDAP: error code 49 - 80090308: LdapErr: DSID-0C0903A9, comment: AcceptSecurityContext error, data 533, v1db1 ] ========= Resolution: The LDAP error code indicates that the Service Account that is used for LDAP binding may be locked out/disabled. To resolve this issue, enable the Service Account and then try again.
TIBCO Spotfire Server 5.5 275 (276)

276 (276)

TIBCO Spotfire Server 5.5