LiveView Server System Configuration

Project-Specific Configuration Files

LiveView Server uses an internal default StreamBase Server configuration file (an sbconf file) that is maintained internally and should never be manually edited.

Instead, to manage LiveView Server configuration settings, place an sbconf file named sbd.sbconf at the root of your Studio project directory and place your settings there. This project-specific sbconf file is automatically merged with the internal LiveView Server configuration settings such that valid project-specific settings take precedence.

If the Project → Properties settings for your LiveView project specify the Automatically update/maintain server configuration files option (on the StreamBaseProject Configuration page), then Studio creates and maintains three server configuration files per project:

sbd.sbconf — For environment-specific settings, primarily used when running this project at the command prompt.
sbd-common.sbconf — For settings common to both command-line and Studio environments.
sbd-studio.sbconf — For settings specific to running projects in Studio, including module search path, resource search path, and Java path settings. This file is automatically maintained by Studio; do not edit or change this file manually.

The sbd.sbconf file is still the top-level configuration file, because it includes the other two files. If your LiveView project has all three server configuration files, make your LiveView-specific edits in the top-level sbd.sbconf file, or in sbd-common.sbconf. For LiveView projects, these project-specific settings are still automatically merged with the internally-maintained LiveView server configuration settings.

Changing System Logging Configuration

See StreamBase Logging in the StreamBase documentation for a full explanation of server logging settings. For LiveView, system logging is controlled by a configuration file. These files are by default installed in the $STREAMBASE_HOME/liveview/server/engine/conf folder. The available logging configuration files are:

logback.xml: Default logging setting.
LVDebugLogback.xml: Enable verbose logging. This setting enables LVDEBUG messages to view detailed information on queries submitted to LiveView Server.
LVAlertDebugLogback.xml: Enable verbose debug for alert functionality.
LVSBDebugLogback.xml: Enable logging of all debugging, including all StreamBase debugging. This setting enables verbose logging for both LiveView Server and the underlying StreamBase Server for multi-layered issues.

By default, LiveView uses logback for logging. You can change the logging configuration by setting the environment variable STREAMBASE_LIVEVIEW_LOG equal to the name of one of the preconfigured log files. For example setting STREAMBASE_LIVEVIEW_LOG=LVDebugLogback.xml will set LiveView Server logging to the verbose level.

Note

LiveView logging settings work in tandem with StreamBase Server logging. Depending on your server configuration settings, you might overwrite one set of logging configurations with another. See the TIBCO StreamBase Administration Guide's article on StreamBase Logging for more information on background mode logging settings.

Setting LiveView JVM Heap Memory

When launching a LiveView application from the command line or from StreamBase Studio, you might receive warnings like:

MemoryConfigTooLow - Maximum heap size configured to be 3,204 MB, which is below recommended size for LiveView production configurations

To avoid such warnings, you can specify a minimum JVM heap size for which the warnings are issued in your configuration file by setting the system property liveview.lvmonitor.min.heapmb in your .lvconf file, as follows:

<sysproperty name="liveview.lvmonitor.min.heapmb" value="2000"/>

Specify the property value in megabytes. In the above example, you would only receive the warnings if the heap size is under 2 GB, which is usually not sufficient for running typical applications.

You can put the property in a new configuration file that links to an existing lvconf. For instructions, see Creating New LiveView Configuration Files.

Setting StreamBase and LiveView Ports

A running LiveView instance uses two ports. Each LiveView instance requires two TCP ports: one for server processes (streambase-port) and one for client connections (liveview-port). By default, these port numbers are 10000 and 10080. When you start a LiveView project, both ports are in use. There are three ways that you can change the port numbers for a server process:

Start the server with the command-line client lv-server and use the --streambase-port and --liveview-port options. The is option supersedes all other options. For example, the following lv-server command would start a project named liveview-project on ports 10001 and 10081:
```
lv-server run --streambase-port 10001 --liveview-port 10081 liveview_project
```
Use the sbd.sbconf file to set the system properties tcp-port and liveview.port. This option supersedes the environment variable option in (3).

To specify port numbers in an sbd.sbconf, set the following options:
- In the <server> element in sbd.sbconf, add the tcp-port parameter:
```
<server> 
<param name="tcp-port" value="new-port-value"/> 
</server> 
```
- In the <java-vm> element, add the liveview.port system property (whose value should differ from that of the tcp-port parameter):
```
<java-vm> 
<sysproperty name="liveview.port" value="different-new-port-value" /> 
</java-vm> 
```
If you are running from StreamBase Studio, edit the ports as follows:
1. Right-click on a project folder, or on any of the lvconf files for a project, and select Run As → External Tools Configurations. This opens the External Tools Configurations dialog.
2. In the Options pane, set the port numbers.
3. Click Run.
Set the environment variables liveview.streambase.connection.pool.port and liveview.port. This option will be overridden by either option (1) or option (2).

Using LiveView Authentication and Authorization

Introduction

LiveView can be configured to verify the identity of clients (authentication) and ensure that authenticated clients have permission to access the requested LiveView resources (authorization).

LiveView authentication and authorization, hereafter referred to as simply authentication, is configured through a properties file, liveview.properties, located in your LiveView project's top-level directory. This file allows you to enable authentication, specify a "security realm," and configure realm-specific attributes. The two security realms are currently supported:

Properties file: Users, passwords, roles, and permissions are configured in a second properties file, liveview.auth.properties, located in your LiveView project's top-level directory
Active Directory server: Users and roles (groups) are retrieved from an Active Directory server, while the mapping of roles to LiveView permissions is retrieved from liveview.auth.properties.

The LiveView Authentication and Authorization sample provides template liveview.properties and liveview.auth.properties files that can be used as the basis for enabling authentication in your LiveView application. To load and run the project, follow the steps in the sample's README.txt file installed in STREAMBASE_HOME/liveview/sample/lv-auth.

Usernames and Passwords in LiveView URIs

When LiveView authentication is enabled, a LiveView client identifies itself to the server with a username and password. These credentials can be included in a LiveView URI by placing them between the protocol field and server name in the URI. For example:

lv://myusername:myPassword@localhost

Note that a colon (:) delimits the username and password, while an at sign (@) delimits the username/password and server name.

Realm Configuration

The template liveview.properties file in the LiveView Authentication sample contains a section for each of the two security realms:

Properties File:

# Properties file authentication/authorization
#
# Uncomment these lines to enable authentication/authorization using a properties file.
#
#liveview.security.auth.filter=authcBasic
#liveview.security.auth.realm=properties
#liveview.security.auth.properties.file=liveview.auth.properties

Active Directory:

# Active Directory authentication/authorization
#
# Uncomment these lines to enable authentication/authorization using Active Directory.
#   
#liveview.security.auth.filter=authcBasic
#liveview.security.auth.realm=activeDirectory
#liveview.security.auth.properties.file=liveview.auth.properties
#
# Uncomment these lines and provide your site-specific Active Directory values:
#
#liveview.security.auth.active.dir.url=ldap://adserver.mycompany.com
#liveview.security.auth.active.dir.username=CN=Administrator,CN=Users,DC=mycompany,DC=com
#liveview.security.auth.active.dir.password=mypassword
#liveview.security.auth.active.dir.search.base=CN=Users,DC=mycompany,DC=com
#liveview.security.auth.active.dir.group.membership.attr=memberOf

To enable authentication, uncomment the lines within liveview.properties pertaining to your chosen security realm. If using a properties file realm, template values are provided that allow the sample to be run out-of-the-box. For Active Directory, replace the template values with your site-specific Active Directory values such as URL, system username and password, or other values.

Enciphered Passwords

Passwords within liveview.properties and liveview.auth.properties can be stored as either clear or enciphered text. Encipher a password as follows:

sbcipher -c "mypassword"
cA8lR8fz+XBf0QaVP0jxTO6LFCWQhL2PagLXTEVF9RFEB6nkFQB9MXKea7qW7+3IhBgXBtxqhkNx0FUPE2jAJw==

Replace the clear text password in liveview.properties, liveview.auth.properties, or sbd.sbconf with the enciphered text returned by sbcipher, e.g.,

liveview.security.auth.active.dir.password=cA8lR8fz+XBf0QaVP0jxTO6LFCWQhL2PagLXTEVF9RFEB6nkFQB9MXKea7qW7+3IhBgXBtxqhkNx0FUPE2jAJw==

LiveView Roles

Each LiveView user can have one or more role. The mapping of users to roles depends upon the configured realm. When using a property file, this mapping is contained in liveview.auth.properties:

# LiveView user-to-role mapping
#user.<name> = <password>,<role1>,<role2>,...
user.lvmanager = lvmanager,LVAdmin
user.lvguest = lvguest,LVUser
user.lvinternal = lvinternal,LVIntern

In the example above, there are three users: lvmanager, lvguest, and lvinternal, which have roles of LVAdmin, LVUser, and LVIntern, respectively. When using Active Directory, user-to-role mapping is retrieved from the Active Directory server using, by default, the memberOf attribute. The Active Directory attribute used for user-to-role mapping can be changed with the liveview.security.auth.active.dir.group.membership.attr property in liveview.properties.

Each role can be assigned one or more permissions, some of which can be hierarchical. Users with multiple roles inherit the permissions from all assigned roles. Role-to-permission mapping is contained in liveview.auth.properties:

# LiveView role-to-permission mapping
#role.<name> = <permission1>,<permission2>,...
role.LVAdmin = *
role.LVUser = connect, table:list, table:manage, table:query:Items, table:publish:Items, 
  table:delete:Items, alert:list, alert:set, alert:delete, session:kill, query:kill, 
  publisher:kill
role.LVIntern = connect, table:query:*

LiveView Permissions

The following table lists the available permissions and their use within LiveView.

Permission Description

* Allows full access to all LiveView resources.

connect Allows a user to connect to LiveView.

publisher[:<operation>]

This hierarchical permission controls the ability to kill LiveView client publishers. It contains between one and two elements delimited with colons. The second element specifies the tuple operation as follows:

*	Allows all operations on the specified streams.
kill	Allows killing of LiveView Publishers.

query[:<operation>]

This hierarchical permission controls the ability to kill LiveView client queries. It contains between one and two elements delimited with colons. The second element specifies the tuple operation as follows:

*	Allows all operations on the specified streams.
kill	Allows killing of LiveView queries.

session[:<operation>]

This hierarchical permission controls the ability to kill LiveView client sessions. It contains between one and two elements delimited with colons. The second element specifies the tuple operation as follows:

*	Allows all operations on the specified streams.
kill	Allows killing of LiveView sessions.

shutdown Allows a user to shut down the LiveView server. This permission is typically granted only to LiveView administrators.

table[:<operation>[:<table-name>]]

This hierarchical permission controls access to LiveView tables. It contains between one and three elements delimited with colons. The second element specifies the table operation as follows:

*	Allows all operations on the specified tables.
list	Allows listing the set of configured LiveView tables. The third element is unused. Listing selected tables can be enabled with the `list:table:<table-name>` permission.
query	Allows querying and listing the specified tables.
ccquery	Allows querying that have calculated columns in projection and listing the specified tables.
publish	Allows publishing to the specified tables.
delete	Allows deleting records from the specified tables.
manage	Allows LiveView tables to be managed via table providers.
add	Allows adding data layer LiveView tables
remove	Allows removing data layer LiveView tables

If the third element is absent, or contains *, the permission applies to all LiveView tables.

tuple[:<operation>[:<stream-name>]]

This hierarchical permission controls access to sending tuples from LiveView clients to StreamBase applications. It contains between one and three elements delimited with colons. The second element specifies the tuple operation as follows:

*	Allows all operations on the specified streams.
info	Allows retrieving schemas associated the specified streams.
send	Allows sending tuples to the specified streams.

If the third element is absent, or contains *, the permission applies to all LiveView tables.

alert[:<operation>[:<table-name>]]

This hierarchical permission controls access to LiveView alerts. It contains between one and three elements delimited with colons. The second element specifies the alert operation as follows:

*	Allows all alert operations.
list	Allows retrieving the set of configured alerts. The third element is unused.
set	Allows adding or modifying alert rules on the specified tables. If the third element is absent, or contains `*`, the permission applies to all LiveView tables.
delete	Allows deleting alert rules. The third element is unused.

alertaction[:<type>[:<table-name>]]

This hierarchical permission controls access to adding LiveView alerts actions. It contains between one and three elements delimited with colons. The second element specifies the type of alert action as follows:

*	Allows adding all types of alert actions.
email	Allows adding an alert action that sends an email message to specified username (or usernames).
java	Allows adding an alert action that executes Java code.
oscmd	Allows adding an alert action that executes an operating system command.
publish	Allows adding an alert action that publishes the alert to a LiveView table.
sendtuple	Allows adding an alert action that sends a tuple to a StreamBase stream.
delete	Allows adding an alert action that deletes rows from a LiveView table.

workspace[:<operation>[:<workspace-name>]]

This hierarchical permission controls access to LiveView workspaces. It contains between one and three elements delimited with a colon. The second element specifies the workspace operation as follows:

*	Allows all workspace operations.
get	Allows listing available workspaces and downloading individual workspaces from the LiveView server.
set	Allows uploading new workspaces to the LiveView server and modifying existing workspaces.
delete	Allows deleting workspaces from the LiveView server.

Internal LiveView User and Role

Several internal LiveView components are required to make requests to access LiveView server resources. When authentication is enabled, these internal requests must be made in the context of a valid LiveView user configured with the appropriate permissions. A special role, LVInternal, is available to satisfy this requirement. Two system properties, liveview.internal.username and liveview.internal.password, specify the credentials of the internal LiveView user configured with the LVInternal role. The LiveView Authentication/Authorization Sample sets the internal user's credentials in a StreamBase configuration file, sbd.sbconf. Enciphered Passwords describes how to encipher passwords, including that for the internal user, for added security.

Dynamic Changes to Users, Roles, and Permissions

Changes to users, roles, and permissions in liveview.auth.properties are recognized dynamically by LiveView. By default, changes are processed within 1 second of this file being saved. The liveview.security.auth.reload.interval.seconds property in liveview.properties can be used to change the interval, in seconds, that LiveView uses to detect changes.

Using SSL

Introduction

Network traffic between LiveView clients and the server can run over a secure connection by enabling LiveView SSL. This is particularly important when authentication is enabled and usernames and passwords are sent over the wire.

To use SSL, configure LiveView server to listen on an SSL port, and direct LiveView clients SSL-enabled connections to that port. When SSL is enabled, the LiveView server, by default, listens on both a non-SSL port and an SSL port. To configure the server to listen on an SSL port only, set the liveview.ssl.only property to true, either in your LiveView project's liveview.properties or StreamBase configuration (sbd.sbconf) file.

Server Configuration

SSL is enabled in the LiveView server by setting the liveview.ssl.port property in one of three ways:

Start the LiveView server with the --liveview-ssl-port option:

lv-server --liveview-ssl-port 10443 run <path-to-lv-project>

In your LiveView project's liveview.properties file, uncomment the line that sets the LiveView SSL port:
```
liveview.ssl.port=10443
```
A template liveview.properties file is provided with the LiveView Authentication/Authorization sample.
In the <java-vm> element of your LiveView project's StreamBase configuration file, sbd.sbconf, set the liveview.ssl.port proprerty:
```
<java-vm>
    <sysproperty name="liveview.ssl.port" value="10443"/>
</java-vm>
```

When SSL is enabled, the LiveView server requires a Java keystore and password to identify itself to LiveView clients, and a Java truststore and password for internal LiveView components that make client requests to the LiveView server. The LiveView Authentication/Authorization sample provides a pre-populated keystore file that is used for both roles and is configured within the sample's StreamBase configuration file, sbd.sbconf, as follows:

<sysproperty name="liveview.keystore" value="mykeystore"/>
<sysproperty name="liveview.keystore.password" value="mypassword"/>
<sysproperty name="javax.net.ssl.trustStore" value="mykeystore"/>
<sysproperty name="javax.net.ssl.trustStorePassword" value="mypassword"/>

LiveView SSL Clients

LiveView URI SSL Protocol and Port

To connect to a LiveView server using SSL, LiveView clients use URIs with a protocol of lvs rather than lv. When configured for SSL, a LiveView server listens, by default, on port 10443. This is also the default port of a LiveView URI when using the lvs protocol. You can override the default LiveView SSL port by adding an explicit port number to the URI, e.g.,

lvs://myusername:myPassword@localhost:10444

LiveView Client Trust Relationship

When connecting to LiveView via SSL, the LiveView client and server perform an SSL handshake, which includes the server sending its certificate to the client. If the client isn't configured to trust the server's certificate, the handshake fails and the connection isn't established. For Java-based SSL clients, such as LiveView Desktop, LiveView Workspace Manager, the lv-client command, or other Java applications that use the LiveView Java client API to connect to the LiveView server, the trust relationship can be configured by setting the javax.net.ssl.trustStore and javax.net.ssl.trustStorePassword properties, respectively, with the path and password of a Java keystore file containing the LiveView server's certificate. When using the LiveView Authentication/Authorization sample, the server's certificate is located in the mykeystore file provided with the sample.

Configuring the trust relationship for non-Java LiveView clients is beyond the scope of this document.

Using StreamBase Authentication with LiveView

How to access StreamBase that has been locked down.

If you are using authentication to protect your StreamBase environment from unintended use, you need to configure your LiveView projects to work with the authentication-enabled StreamBase Server.

To enable LiveView to run with a StreamBase server on which authentication is enabled, you must set four LiveView system properties:

liveview.streambase.admin.username: The username of an SBAdmin-enabled StreamBase user.
liveview.streambase.admin.password: The password of an SBAdmin-enabled StreamBase user.
liveview.streambase.user.username: The username of the StreamBase user without SBAdmin privileges.
liveview.streambase.user.password: The password of the StreamBase user without SBAdmin privileges.

The following StreamBase configuration file, placed in the top-level directory of the project directory, enables StreamBase authentication (using the parameters under the <authentication> tag) and allows LiveView Server to run with the authentication-enabled StreamBase Server (using the systems properties under the <java-vm> tag):

<?xml version="1.0"?>

<streambase-configuration xmlns:xi="http://www.w3.org/2001/XInclude"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:noNamespaceSchemaLocation="http://www.streambase.com/schemas/sbconf/">

    <authentication>
        <param name="enabled" value="true"/>
        <param name="type" value="sb-password-file"/>
        <param name="filepath" value="./sbpasswd"/>
    </authentication>
    
    <java-vm> 
        <sysproperty name="liveview.streambase.admin.username" value="sbmanager" /> 
        <sysproperty name="liveview.streambase.admin.password" value="sbmanager" />
        <sysproperty name="liveview.streambase.user.username" value="sbtest" /> 
        <sysproperty name="liveview.streambase.user.password" value="sbtest" />
    </java-vm>

To match this configuration create the users as follows:

sbuseradmin -f sbpasswd --add -n sbmanager -p sbmanager -r SBAdmin
sbuseradmin -f sbpasswd --add -n sbtest -p sbtest -r SBUser

To encipher the passwords in this configuration, for each password run the following commands (commands shown on two lines for clarity):

sbcipher -c"sbmanager" 
  mF4Tooh8qipplnZwa6PN3qLhuxAosmGBpxriEmhVVuqWphq+rXBybWV6XfxZUgMWwUvmcqtiy5UcbIVlMCswLw==

sbcipher -c"sbtest"
  KX4vUpjZgQfav3gHujZ08jqeJtvJFX+WyNu4nzX4TBhGErDVDGRfHjKI7yXn/jW4OXx4Bei7hXlGxjKAg0hTmw==

Now, replace the password properties with these values:

<sysproperty name="liveview.streambase.admin.password" 
value="mF4Tooh8qipplnZwa6PN3qLhuxAosmGBpxriEmhVVuqWphq+rXBybWV6XfxZUgMWwUvmcqtiy5UcbIVlMCswLw==" />

<sysproperty name="liveview.streambase.user.password" 
value="KX4vUpjZgQfav3gHujZ08jqeJtvJFX+WyNu4nzX4TBhGErDVDGRfHjKI7yXn/jW4OXx4Bei7hXlGxjKAg0hTmw==" />

Configuring the Location of Generated Files and Metadata

By default, when you run a LiveView project, LiveView creates an lv-bin directory for generated project files and an lv-systemdata directory for generated project data. (These directories are hidden by default; you can change the default view with the Package Explorer filters.) You can add a system property to the project sbconf file (liveview.project.out) that defines a writable folder for files and metadata that LiveView Server generates:

<sysproperty value="..\out" name="liveview.project.out"/>

The value of this property can be an absolute or relative path. If it is a relative path, it will be appended to the liveview.project.home. If the specified folder is not writable, LiveView throws an exception. LiveView Server redirects all generated files and metadata to this path.

The lv-bin folder is written under the specified folder (for example, ..\out\lv-bin). If this property is not specified, the output folder is assumed to be the project home (lv-bin is then created in \project_home\lv-bin.) The the project_home folder is not writable, the compiler first tries the user's folder and then tries the temp folder. This information is logged. If LiveView cannot find a writable folder, it throws an exception.

If only 'sysproperty name="liveview.project.out"...' is set, SB/LV writes lv-bin and lv-systemdata to the lv.project.out directory.

If both 'sysproperty name="liveview.project.out"...' and 'sysproperty name="liveview.systemdata.directory"...' are set, lv-bin goes into lv.project.out and lv-systemdata goes in lv.systemdata.directory.

If only 'sysproperty name="liveview.systemdata.directory"...' is set, lv-bin goes in the project workspace and lv-systemdata goes in lv.systemdata.directory.