APPENDIX C       Scripts

This section describes scripts that are available for RTView Enterprise as well as the rtvservers.dat configuration file. This section also includes scripts for other RTView components. This section includes:

Scripts

The following scripts are available when used from an initialized command window. The scripts can be executed from a Windows Command Prompt or UNIX terminal window. On Windows, you can type the commands as described in this section. On UNIX systems, you must add .sh to each command. For example, rtvapm_init.sh. Also on UNIX systems, it is a requirement that the installation directory path not contain spaces.

These instructions assume use of a BASH or a BASH-compliant shell.

Script Name

Description

encode_string

Script to create an encoded version of a password
Location:
rtvapm/rtview/bin
Format:
encode_string encoder2 <password>
This will give you an encrypted value for "password" that you can use in your properties.

my_alert_actions.bat/sh

Sample script to define actions for alerts.

Location:

The project directory.

Format:

my_alert_actions
(Append .sh on UNIX)

rtv_hardkill.sh

Script to "hard" kill (using linux "kill -9") RTView server processes, the RTView Host Agent, and the Apache Tomcat that is bundled with some RTView products. This script is useful when RTView processes are not receiving the normal jmx termination command, or when expediency is more important than data retention.

 

Location:

rtvapm/common/bin

This script can be run anywhere in the initialized linux terminal window.

 

Format:

rtv_hardkill.sh [-f]

To skip the confirmation prompt, use the -f argument.

It can also be invoked in the stop_servers.sh script by passing in the -hardkill option. See that script for further details.

Warning! Note that rtv_hardkill.sh will kill all RTView server processes on the system, not just those within the installation you are running it from. For example, if you are running RTViewCentral and an RTViewDataServerX installation on the same system, rtv_hardkill.sh will terminate both RTView Central Servers and the RTView DataServer. If you do not wish for rtv_hardkill.sh to terminate the RTView-bundled Apache Tomcat nor RTView Host Agent, you can comment out those lines in rtvapm/common/bin/rtv_hardkill.sh.

rtv_setup.bat/sh

Initializes a command prompt or terminal window.

Location:

<installation directory>/bin

This script must be executed in the directory in which it resides.

Format:

rtv_setup
(Append .sh on UNIX)

rtvapm_init.bat/sh

Initializes a command window.

Location:

rtvapm

This script must be executed in the directory in which it resides.

Format:

Windows: rtvapm_init

Linux: . ./rtvapm_init.sh

start_cmd.bat

Starts an initialized Command Prompt window on Windows.

Location:

<installation directory>/bin

This script must be executed in the directory in which it resides. You can also execute the script by double-clicking in an Explorer window.

start_rtv.bat/sh

Starts processes in an RTView configuration as specified in the rtvservers.dat configuration file.

Location:
rtvapm/common/bin

This script must be executed in the project directory (the directory containing the rtvservers.dat file). This script requires rtvapm_init.bat/sh be executed first.

An RTView configuration might include a Data Server, an Historian and a Central Server Database. start_rtv only attempts to start processes it detects are not running. The action can be applied to all RTView configurations, a single RTView configuration or a single process in an RTView configuration.

Before starting an RTView server, this script detects port conflicts caused by another server. If the conflict is caused by another RTView server, it returns a message identifying that server by its rtvapm. For example:

...start_rtv.bat: another dataserver running with JMX port 3268 under C:\rtview\RTViewDataServer\rtvapm

 

If the port conflict is caused by a non-RTView process, it returns a message similar to this, for example:

...start_rtv.bat: JMX port 3268 in use by PID 1234

In both cases the script includes this advice:

Warning: server not started, port conflict

 

 

To avoid port conflicts, run your start script with the -portprefix: command line argument to change the first two (2) digits of all your server ports.

To persist these port changes, change the port prefix in the RTView Configuration Application or use the -saveportprefix command line argument.

Additional arguments can be included on the command line in which case they are passed to every server specified by the command.

Additional arguments can also be included in the rtvservers.dat file, in which case they are only applied to the specific server in whose command they are included.

Note: If you use the -properties or -propfilter argument with start_rtv, you should also use them with status_rtv and stop_rtv. Those commands use the JMX ports defined for the server, and if any of the properties specified by -properties or -propfilter arguments change those ports, subsequent commands will be unable to find the server unless also given those properties.

 

 

–console (or –c) - Start the processes with a command window (which is useful for testing).

When used without arguments, this script returns usage information and a list of available configurations. For example, start_rtv returns:

Usage: start_rtv config or 'all' [server or 'all'] [args...]

Available configs:

default

dataserver

historian

database

sender

dataserver

 

 

all

Starts all RTView configurations that are specified in the rtvservers.dat file.

all applies the action to all RTView configurations specified in the rtvservers.dat file (and corresponding servers or clients specified in each configuration).

Note: When multiple configurations are specified in the rtvservers.dat file and they have different project settings directory locations, the all argument processes all the configurations. However, if the configurations have the same project settings directory locations, the all argument processes only the first configuration as the others are considered alternative configurations.

Example:

start_rtv all
(Append .sh on UNIX)

 

[Configuration Name]

Starts a single RTView configuration specified in the rtvservers.dat file:

start_rtv [Configuration Name]
(Append .sh on UNIX)

Configuration Name is the RTView configuration name specified in the rtvservers.dat file. The action applies to all servers or clients specified in the configuration.

Example:

start_rtv web_deployment
(Append .sh on UNIX)

 

[Server Name]

Starts a single process in an RTView configuration specified in the rtvservers.dat file:

start_rtv [Configuration Name] [Server Name]
(Append .sh on UNIX)

Server Name is the name of a server or client member in the configuration. For example, dataserver, historian and database. The action applies only to that server or client in the configuration.

Example:

start_rtv web_deployment dataserver
(Append .sh on UNIX)

 

Use With Secured JMX Ports

This script works with RTView servers whose JMX ports are secured with either a username and password, or with SSL. You provide the scripts with the necessary credential information and the scripts manage authentication with the server. There are two ways that you can provide credential information to the scripts: via command-line arguments and via properties placed in any property file that is used by the server.

 

Securing with username and password

• To secure with a username and password via command-line, use the arguments as follows:

-jmxuser:...

-jmxpass:...

• To secure with a username and password in a property file, use the properties as follows:

sl.rtview.jmxremote.username=...

sl.rtview.jmxremote.password=....

 

Securing with SSL

To secure with SSL, you provide the client KeyStore and TrustStore locations and their corresponding passwords.

• To secure with SSL via command-line, use the arguments as follows:

-sslkeystore:...

-sslkeystorepass:...

-ssltruststore:...

-ssltruststorepass:...

• To secure with SSL in a property file, use the properties as follows:

sl.rtview.ssl.client.keyStore=...

sl.rtview.ssl.client.keyStorePassword=...

sl.rtview.ssl.client.trustStore=...

sl.rtview.ssl.client.trustStorePassword=....

 

Password Encryption

To encrypt the passwords in your properties files, use the command-line tool "encode_string", for example:

encode_string encoder2 <password>

This will give you an encrypted value for "password" that you can use in your properties.

start_collector.bat/sh

Starts the RTView DataCollector.

Location:

<installation directory>

This script must be executed in the directory in which it resides. You can also execute the script by double-clicking in an Explorer window.

Format:

start_collector
(Append .sh on UNIX)

start_server.bat/sh

Starts the RTView DataServer.

Location:

<installation directory>

This script must be executed in the directory in which it resides. You can also execute the script by double-clicking in an Explorer window.

Format:

start_server
(Append .sh on UNIX)

start_servers.bat/sh

Starts the RTViewCentral servers.

Location:

<installation directory>/bin

This script must be executed in the directory in which it resides. You can also execute the script by double-clicking in an Explorer window.

Format:

start_servers
(Append .sh on UNIX)

start_tomcat.bat/sh

Starts Apache Tomcat.

Location:

<installation directory>/bin

This script must be executed in the directory in which it resides. You can also execute the script by double-clicking in an Explorer window.

Format:

start_tomcat
(Append .sh on UNIX)

status_collector.bat/sh

 

Returns the status of RTView DataCollector.

Location:
<installation directory>

This script must be executed in the project directory (the directory containing the rtvservers.dat file).

Format:

status_collector
(Append .sh on UNIX)

status_rtv.bat/sh

Returns the status of all RTView configurations that are specified in the rtvservers.dat configuration file.

Location:
rtvapm/common/bin

This script must be executed in the project directory (the directory containing the rtvservers.dat file). This script requires rtvapm_init.bat/sh be executed first.

This action uses defined JMX ports. An RTView configuration might include a Data Server, an Historian and a Central Server Database. status_rtv only attempts to start processes it detects are not running. The action can be applied to all RTView configurations, a single RTView configuration or a single process in an RTView configuration.

Additional arguments can be included on the command line in which case they are passed to every server specified by the command. Additional arguments can also be included in the rtvservers.dat file, in which case they are only applied to the specific server in whose command they are included.

Note that if you use -properties or -propfilter arguments with start_rtv, you should also use them with status_rtv and stop_rtv. Those commands use the JMX ports defined for the server, and if any of the properties specified by -properties or -propfilter arguments change those ports, subsequent commands will be unable to find the server unless also given those properties.

 

all

Returns the status of all RTView configurations specified in the rtvservers.dat file. Note: When multiple configurations are specified in the rtvservers.dat file and they have different project settings directory locations, the all argument processes all the configurations. However, if the configurations have the same project settings directory locations, the all argument processes only the first configuration as the others are considered alternative configurations.

Example:

status_rtv all
(Append .sh on UNIX)

 

[Configuration Name]

Returns the status of a single RTView configuration specified in the rtvservers.dat file:

status_rtv [Configuration Name]
(Append .sh on UNIX)

Configuration Name is the RTView configuration name specified in the rtvservers.dat file. The action applies to all servers or clients specified in the configuration.

Example:

status_rtv web_deployment
(Append .sh on UNIX)

 

[Server Name]

Returns the status of a single process in an RTView configuration specified in the rtvservers.dat file:

status_rtv [Configuration Name] [Server Name]
(Append .sh on UNIX)

Server Name is the name of a server or client member in the configuration. For example, dataserver, historian and database. The action applies only to that server or client in the configuration.

Example:

status_rtv web_deployment dataserver
(Append .sh on UNIX)

 

Use With Secured JMX Ports

This script works with RTView servers whose JMX ports are secured with either a username and password, or with SSL. You provide the scripts with the necessary credential information and the scripts manage authentication with the server. There are two ways that you can provide credential information to the scripts: via command-line arguments and via properties placed in any property file that is used by the server.

 

Securing with username and password

• To secure with a username and password via command-line, use the arguments as follows:

-jmxuser:...

-jmxpass:...

• To secure with a username and password in a property file, use the properties as follows:

sl.rtview.jmxremote.username=...

sl.rtview.jmxremote.password=....

 

Securing with SSL

To secure with SSL, you provide the client KeyStore and TrustStore locations and their corresponding passwords.

• To secure with SSL via command-line, use the arguments as follows:

-sslkeystore:...

-sslkeystorepass:...

-ssltruststore:...

-ssltruststorepass:...

• To secure with SSL in a property file, use the properties as follows:

sl.rtview.ssl.client.keyStore=...

sl.rtview.ssl.client.keyStorePassword=...

sl.rtview.ssl.client.trustStore=...

sl.rtview.ssl.client.trustStorePassword=....

 

Password Encryption

To encrypt the passwords in your properties files, use the command-line tool "encode_string", for example:

encode_string encoder2 password

This will give you an encrypted value for "password" that you can use in your properties.

status_server.bat/sh

Returns the status of the RTView DataServer.

Location:
<installation directory>

This script must be executed in the project directory (the directory containing the rtvservers.dat file).

Format:

status_server
(Append .sh on UNIX)

status_servers.bat/sh

Returns the status of the RTViewCentral servers (as well as the Solace PubSub+ Monitor in SolacePubSubMonitor).

Location:
<installation directory>/bin

This script must be executed in the project directory (the directory containing the rtvservers.dat file).

Format:

status_servers
(Append .sh on UNIX)

stop_collector.bat/sh

Stops the RTView DataCollector.

Location:

<installation directory>

This script must be executed in the directory in which it resides. You can also execute the script by double-clicking in an Explorer window.

Format:

stop_collector
(Append .sh on UNIX)

stop_rtv.bat/sh

Stops processes in an RTView configuration as specified in the rtvservers.dat configuration file.

Location:
rtvapm/common/bin

This script must be executed in the project directory (the directory containing the rtvservers.dat file). This script requires rtvapm_init.bat/sh be executed first.

This action uses defined JMX ports. An RTView configuration might include a Data Server , an Historian and a Central Server Database. stop_rtv only attempts to start processes it detects are not running. The action can be applied to all RTView configurations, a single RTView configuration or a single process in an RTView configuration.

Additional arguments can be included on the command line in which case they are passed to every server specified by the command. Additional arguments can also be included in the rtvservers.dat file, in which case they are only applied to the specific server in whose command they are included.

Note that if you use -properties or -propfilter arguments with start_rtv, you should also use them with status_rtv and stop_rtv. Those commands use the JMX ports defined for the server, and if any of the properties specified by -properties or -propfilter arguments change those ports, subsequent commands will be unable to find the server unless also given those properties.

Location:

project directory

This script must be executed in the project directory (the directory containing the rtvservers.dat file).

 

all

Stops all RTView configurations that are specified in the rtvservers.dat file. all applies the action to all RTView configurations specified in the rtvservers.dat file (and corresponding servers or clients specified in each configuration). Note: When multiple configurations are specified in the rtvservers.dat file and they have different project settings directory locations, the all argument processes all the configurations. However, if the configurations have the same project settings directory locations, the all argument processes only the first configuration as the others are considered alternative configurations.

Example:

stop_rtv all
(Append .sh on UNIX)

 

[Configuration Name]

Stops a single RTView configuration specified in the rtvservers.dat file:

stop_rtv [Configuration Name]
(Append .sh on UNIX)

Configuration Name is the RTView configuration name specified in the rtvservers.dat file. The action applies to all servers or clients specified in the configuration.

Example:

stop_rtv web_deployment
(Append .sh on UNIX)

 

[Server Name]

Stops a single process in an RTView configuration specified in the rtvservers.dat file:

stop_rtv [Configuration Name] [Server Name]
(Append .sh on UNIX)

Server Name is the name of a server or client member in the configuration. For example, dataserver, historian and database. The action applies only to that server or client in the configuration.

Example:

stop_rtv web_deployment dataserver
(Append .sh on UNIX)

 

Use With Secured JMX Ports

This script works with RTView servers whose JMX ports are secured with either a username and password, or with SSL. You provide the scripts with the necessary credential information and the scripts manage authentication with the server. There are two ways that you can provide credential information to the scripts: via command-line arguments and via properties placed in any property file that is used by the server.

 

Securing with username and password

• To secure with a username and password via command-line, use the arguments as follows:

-jmxuser:...

-jmxpass:...

• To secure with a username and password in a property file, use the properties as follows:

sl.rtview.jmxremote.username=...

sl.rtview.jmxremote.password=....

 

Securing with SSL

To secure with SSL, you provide the client KeyStore and TrustStore locations and their corresponding passwords.

• To secure with SSL via command-line, use the arguments as follows:

-sslkeystore:...

-sslkeystorepass:...

-ssltruststore:...

-ssltruststorepass:...

• To secure with SSL in a property file, use the properties as follows:

sl.rtview.ssl.client.keyStore=...

sl.rtview.ssl.client.keyStorePassword=...

sl.rtview.ssl.client.trustStore=...

sl.rtview.ssl.client.trustStorePassword=....

 

Password Encryption

To encrypt the passwords in your properties files, use the command-line tool "encode_string", for example:

encode_string encoder2 password

This will give you an encrypted value for "password" that you can use in your properties.

stop_server.bat/sh

Stops the RTView DataServer.

Location:

<installation directory>

This script must be executed in the directory in which it resides.

Format:

stop_server
(Append .sh on UNIX)

stop_servers.bat/sh

Stops the RTViewCentral servers.

Location:

<installation directory>/bin

This script must be executed in the directory in which it resides. You can also execute the script by double-clicking in an Explorer window.

Format:

stop_servers
(Append .sh on UNIX)

To execute rtv_hardkill.sh as the final step of this script, include argument -hardkill [n]. The optional 'n' is the number of seconds to delay before executing a hard kill. If 'n' is not specified, this script will wait 65 seconds after normal process shutdown is performed. This default duration is recommended because the normal shutdown method can take up to 60 seconds to cleanly terminate all threads.

Warning! Note that rtv_hardkill.sh will kill all RTView server processes on the system, not just those within the installation you are running it from. For example, if you are running RTViewCentral and an RTViewDataServerX installation on the same system, rtv_hardkill.sh will terminate both RTView Central Servers and the RTView DataServer. If you do not wish to terminate the RTView-bundled Apache Tomcat nor RTView Host Agent, you can comment out those lines in rtvapm/common/bin/rtv_hardkill.sh.

stop_tomcat.bat/sh

Stops Apache Tomcat.

Location:

<installation directory>/bin

This script must be executed in the directory in which it resides.

Format:

start_tomcat
(Append .sh on UNIX)

update_wars.bat/sh

Creates/updates the primary Monitor servlets.

 

Location:

<installation directory>/projects/rtview-server

This script must be executed in the directory in which it resides. This script requires rtvapm_init.bat/sh be executed first.

 

Format:

update_wars.sh [appname [host [portprefix]]]

 

For example:

update_wars.sh my-appname my-hostname 99

 

The name, host, and portprefix are declared in variables at the top of the script for easy editing, and can be passed into the scripts on the command-line.

 

-secure

Use the "-secure" argument to update the rtvquery war with security enabled.

You can use ? or help to get a usage message. For example:

update_wars.sh help

 

You can edit other variables at the top of the scripts to set properties for high-availability (HA).

Set HA_HOST to the hostname of the backup data server.

upgrade_rtv.bat/sh

Migrates common configuration from a previous installation of RTViewCentral, RTViewDataServer, or SolacePubSubMonitor to the new installation.

 

Location:

rtvapm/common/bin

This script requires rtvapm_init.bat/sh be executed first in the new installation.

 

Format:

upgrade_rtv old-install [old-tomcat] [new-tomcat]

(Append .sh on UNIX)

 

For example:

upgrade_rtv.sh ~/rtv61/RTViewCentral

 

If upgrading RTViewCentral or SolacePubSubMonitor, Apache Tomcat configuration will be copied. The bundled Apache Tomcat will be used unless both old-tomcat and new-tomcat are given as arguments.

If upgrading RTViewDataserver, old-tomcat can be given as argument and the RTViewDataServer's war files will be rebuilt and installed in the specified Tomcat (SL-supplied or otherwise). If new-tomcat is also given its configuration will be updated from old-tomcat.

Configuration that is copied includes:

• projects directory
• permanent license KEYS file
• projects\custom\src is rebuilt
• where applicable (see usage statement above), Apache Tomcat conf directory is copied, and project .war files are rebuilt and copied to Apache Tomcat webapps directory

Limitations:

• Changes outside of the projects directory will not be retained, so users are reminded to not make edits to configuration files under the rtvapm directory.
• The scripts do not interface with any databases. Users who are still utilizing the evaluation HSQLDB databases will need to copy or recreate their tables. Customers who are using product databases should not need to take any additional steps since the imported project will persist their existing database connections. If there are any changes required in the database tables, they will be provided in the Manual Upgrade Steps (for changes to existing tables) that print at the end of the script or in the Release Notes (for new tables).
• Configuration for LDAP setup is not migrated
• Upgrading an RTViewDataCollector deliverable is not supported, but users can upgrade from an old RTViewDataCollector installation to a new RTViewDataServer installation.

 

validate_install.bat/sh

Use this script if you encounter error messages when starting servers, to verify your system environment (for example, to verify that Java is installed) as well as your installation directories.

Location:

RTVAPM_HOME

This script must be executed in the directory in which it resides.

Also, in Unix, this script checks and corrects file permissions and file formats (if, for example, the wrong unzip command was used during installation). If file permissions or formats are fixed, the script returns a count of the files fixed. Additionally, if invoked with the argument "-v" (verbose) it returns the names of the files fixed.

The script returns the following information (where <RTViewInstallation> is your RTView installation):

• In Windows

Validating installation in /opt/rtview/<RTViewInstallation>

... Java installation correct.

... rtvapm installation correct.

• In UNIX

Validating installation in /opt/rtview/<RTViewInstallation>

... Java installation correct.

... rtvapm installation correct.

... file permissions correct.

... file formats correct.

rtvservers.dat

This section describes the rtvservers.dat configuration file which is used to manage your RTView deployment and processes. This section includes:

• Single Configuration File
• Multiple Configuration File

The rtvservers.dat text file contains one or more RTView configurations. An RTView configuration is a group of servers that should be started together. For example, the configuration might include any of the following: a Data Server, Historian, and an HSQLDB database. The rtvservers.dat file is used when the following scripts are executed:

• start_rtv Starts RTView processes specified in the rtvservers.dat file.
• stop_rtv Stops the RTView processes specified in the rtvservers.dat file.
• status_rtv Returns status information for RTView processes specified in the rtvservers.dat file.

Single Configuration File

The following rtvservers.dat file, located in your project directory, contains a single RTView configuration, named default.

default . dataserver rundata

default . historian runhist -ds

default . database rundb

Note: The last line in the rtvservers.dat file must end with a new line, or be followed by a blank line.

In this example, to start the default configuration type: start_rtv default or start_rtv all. To start a single server in the configuration, type start_rtv <Configuration Name> <Server Name>. For example: start_rtv default dataserver.

Each line has the following format consisting of four fields:

<Configuration Name> <Project Settings Directory Location> <Property Filter Identifying the Server> <Command>

<Configuration Name>

The name of the RTView configuration (default in this example).

<Project Settings Directory Location>

The RTView project settings directory location, relative to the location of the rtvservers.dat file (., the current directory, in this example).

<Property Filter Identifying the Server>

The property filter that identifies the server, which is the property filter under which the server’s JMX port is defined. By default, this is the server name, such as dataserverand historian.

<Command>

The script used to start the process. Valid values are:

• rundata: Starts the Data Server.
• runhist: Starts the Historian.
• rundb: Starts the HSQLDB Database.

Multiple Configuration File

When multiple configurations are specified in the rtvservers.dat file and they have different project settings directory locations, the all argument processes all the configurations. However, if the configurations have the same project settings directory locations, the all argument processes only the first configuration as the others are considered alternative configurations. Alternative configurations allow you to alternate between two configurations for a single RTView deployment.

For example, the following rtvservers.dat file, located in your project directory/servers directory, contains two configurations, bwmon and emsmon. Note that the project settings directory locations differ (./bwmon and ./emsmon, respectively).

bwmon ./bwmon dataserver rundata
bwmon ./bwmon historian runhist -ds

emsmon ./emsmon dataserver rundata
emsmon ./emsmon historian runhist -ds

Because the project settings directory locations differ, you can use type start_rtv all to start both configurations. To start only the bwmon configuration, type: start_rtv bwmon. To start a single server in the bwmon configuration, type start_rtv <Configuration Name> <Server Name>. For example: start_rtv bwmon dataserver.