5.0 Documentation

 

General configuration

Many of the configuration tasks described in this section can be accomplished within the server's graphical interface using the Configuration page. Other tasks will require you to edit the configuration files directly from the server's installed directory. The file structure within the directory is described in Configuration file hierarchy.

Most of the configurable properties described in this section can be found in the cluster-plugin.xml and cluster-plugin.properties files. A complete list of these properties, with brief descriptions, is provided in Configurable properties.

In earlier versions, it was possible to cluster several nodes on the same server, which is why some references to "cluster", "clustering" and "nodes" linger in filenames and property names. Nowadays, multi-server environments are managed through load balancers instead


Configuration page

The server’s Configuration page, available to users with administrator-level credentials, contains a list of configuration links, divided in three sections: at the top, general server configuration, followed by logging configuration, and finally system configuration.

To access this page, log into the server and click the Configuration link, or navigate to the page directly assuming you are already logged in:
http://[server]:[port]/pureweb/config/plugins


Not all configuration files are accessible from this page. If a file is not on that page, it must be edited manually by opening it in a text editor from the server’s installed directory.

The list of files on this page will vary depending on which plug-ins are installed. For information on how to add an application plug-in, see Add application plug-ins to the server.

Configuration file editing

The name of each file in the Configuration page is a link that opens the content of the file in an editor page within your browser. The editor has a simple interface where you can type in your changes, and provides a Cancel and a Save button at the bottom of the page. After you edit a file and save your changes, the system returns to the Configuration page.

You must perform a reload or restart the server before server configuration or plug-in file changes take effect.

To perform a reload, navigate to the server's Configuration page and click the Reload button for the section where the file is located within the page (for example, if you edited a plug-in configuration file, click the Reload Plugins button, if you edited a logging configuration file, click the Reload Logging button, and so on).

If you edit a configuration file, the server will display a reload required message beside this file in the Configuration page as a reminder until the changes have been applied.


Configuration file hierarchy

The server is implemented as a standard Java Web Application, using common Java components including the Apache Tomcat 7.0 web container and various libraries from the Spring Framework. The hierarchy of configuration files is defined by these technologies, as well as the underlying server plug-in architecture. Installation of optional plug-ins will add specific .xml and .properties files to the list of configuration files in the conf directory.

The table below lists the most common configuration files, which you'll find in the [install_path]\tomcat-server directory.

Configuration File and Path Description
\webapp\WEB-INF\
web.xml
Standard Java Servlet Specification 2.4 Web Application definition loaded by Apache Tomcat. Defines the PureWeb server web application.
\webapp\WEB-INF\
pureweb-context.xml
Standard Spring Framework Root Web Application Context loaded by the web application defined in web.xml. The context defines the authentication facilities used by all components within the PureWeb server.
\webapp\WEB-INF\
dispatcher-servlet.xml
Standard Spring Framework Servlet Dispatcher loaded by the web application defined in web.xml. Defines common facilities used by various components of the PureWeb server.
\conf\security-config.xml Additional security configuration allowing various plug-ins to define their own security requirements using Java annotations.
\conf\pureweb.xml Common logging, error handling and configuration management facilities provided by the PureWeb server.
\conf\cluster-plugin.xml Application hosting facilities.
\conf\cluster-plugin.properties Basic configuration properties referenced by the cluster-plugin.xml file above.
Configuration file and path Description
\webapp\WEB-INF\web.xml Standard Java Servlet Specification 2.4 Web Application definition loaded by Apache Tomcat. Defines the PureWeb server web application.
\webapp\WEB-INF\pureweb-context.xml Standard Spring Framework Root Web Application Context loaded by the web application defined in web.xml. The context defines the authentication facilities used by all components within the PureWeb server.
\webapp\WEB-INF\dispatcher-servlet.xml Standard Spring Framework Servlet Dispatcher loaded by the web application defined in web.xml. Defines common facilities used by various components of the PureWeb server.
\conf\security-config.xml Additional security configuration allowing various plug-ins to define their own security requirements using Java annotations.
\conf\pureweb.xml Common logging, error handling and configuration management facilities provided by the PureWeb server.
\conf\cluster-plugin.xml Application hosting facilities.
\conf\cluster-plugin.properties Basic configuration properties referenced by the cluster-plugin.xml file above.

Configuring the ports

You can configure the ports for communications between the server and the service, and between the server and the client.

Client to server (default port 8080)

By default, the PureWeb server runs on port 8080. This is also the port that the server uses to accept connections from the client. This port must be open as inbound on the server and outbound on the computer running the client.

You can change this port configuration in the following file on the server:
[install_path]/tomcat-server/tomcat/conf/server.xml

Within this file, edit the following XML block:

<!-- Define a non-SSL HTTP/1.1 Connector on port 8080 -->
    <!-- When enabling SSL, uncomment the 8443 connector below.  -->
    <!-- Make sure this 8080 connector is still valid as it may still be needed by the apps. -->
    <Connector port="8080" address="0.0.0.0"
        maxHttpHeaderSize="8192"
        maxKeepAliveRequests="-1"
        maxThreads="500" minSpareThreads="25"
        enableLookups="false" redirectPort="8443" acceptCount="100"
        connectionTimeout="600000" disableUploadTimeout="true"
        useBodyEncodingForURI="true" URIEncoding="UTF-8" />

Service to server (default port 8082)

The port that the server uses to accept connections from the service is TCP port 8082.

You can change this port configuration by editing the application.connection.port variable in the following file on the server:
[install_path]/tomcat-server/conf/cluster-plugin.properties


Configuring CORS

Cross-origin resource sharing (CORS) is configured through the web.xml file.

The default configuration simply provides a basic filter, as indicated by the following lines:

<filter>
    <description>
        This filter allows adds headers required for Cross Origin Resource Sharing.
        http://www.w3.org/TR/cors/
        See: http://tomcat.apache.org/tomcat-7.0-doc/config/filter.html#CORS_Filter
    </description>
    <filter-name>CrossOriginResourceSharing</filter-name>
    <filter-class>org.apache.catalina.filters.CorsFilter</filter-class>
</filter>

To fine-tune the filter, you can add parameters, such as a list of allowed origins and a list of exposed headers. Below is sample code for this, you would add these lines after the filter-name and filter-class entries:

<init-param>
    <param-name>cors.allowed.origins</param-name>
    <!-- If you're using IP instead of localhost, replace 'localhost' with IP address. 
    The param value also accepts a comma-separated list of allowed origins. 
    For examples http://localhost:8000, http://10.1.20.36:8000 -->
    <param-value>http://localhost:8000</param-value>
</init-param>
<init-param>
    <param-name>cors.exposed.headers</param-name>
    <param-value>Access-Control-Allow-Origin,Access-Control-Allow-Credentials</param-value>
</init-param>
<init-param>
    <param-name>cors.support.credentials</param-name>
    <param-value>true</param-value>
</init-param>

To disable CORS, you would simply comment out the entire filter.


Configuration backup and restore

The server’s Configuration page offers functionality that makes it easy to back up and restore your configuration information.

Backup Procedure

  1. Log into the server and click the Configuration link to open the server’s Configuration page.
  2. Scroll down the page until you see the System Configuration section.
  3. Under Administration, click on the link labeled Backup/Restore Configuration. This will display the Configuration Backups page, illustrated below.


  4. Click the Save New Backup button.

Your backup will appear under the Save New Backup button, in the form of a radio button labeled with the backup timestamp. As you create new backups, they will also appear in that section, in chronological order, with the most recent one at the bottom of the list.

The backup file itself is a .zip file saved at the following location:
[Install_path]\tomcat-server\conf\backups

Restore Procedure

  1. Log into the server and click the Configuration link to open the server’s Configuration page.
  2. Scroll down the page until you see the System Configuration section.
  3. Under Administration, click on the link labeled Backup/Restore Configuration.
  4. Select the backup to restore from by clicking its radio button.
  5. Click the Restore Selected Backup button.

From the Configuration Backups page, you can use the export and import features to simplify the task of configuring a multi-node cluster.

Export a selected backup to your client machine and save it there to establish common configuration on one server, then use the import option to restore on several other PureWeb servers.

The Configuration Backups page also has a Delete Selected Backup option, which deletes the selected backup permanently.


Configurable properties

There are two configuration files that govern the information shown on the server's Status page:

  • cluster-plugin.properties
  • cluster-plugin.xml

The properties in these files are also used to configure timeouts, as well as client-server and service-server interactions.

Cluster properties

Use the properties below, found in the cluster-plugin.properties file, to manage some of the timeouts and socket-based connections between the PureWeb server and the service application.

Name Description
cluster.
response.
timeout

Defines the length of time that the PureWeb server should wait for responses from the service.

We recommend that you keep this value small, but never less than three seconds. When debugging, increase the value to prevent the middle tier from closing the communication channels on a processed that has been stepped into with a debugger.

Example:
cluster.response.timeout=10

cleanup
Timeout

Defines the amount of time to wait between periodic checks for inactive or abandoned client sessions. The default is 5 seconds.

application.
connection.
address
Defines the address for socket based service connections.
application.
connection.
port
Defines the port for socket-based service connections.
Name Description
cluster.response.timeout

Defines the length of time that the PureWeb server should wait for responses from the service.

We recommend that you keep this value small, but never less than three seconds. When debugging increase the value to prevent the middle tier from closing the communication channels on a processed that has been stepped into with a debugger.

Example: cluster.response.timeout=10

cleanupTimeout

Defines the amount of time to wait between periodic checks for inactive or abandoned client sessions. The default is 5 seconds.

application.connection.address Defines the address for socket based service connections.
application.connection.port Defines the port for socket-based service connections.

Node properties

Use the properties below, found in the cluster-plugin.xml file, to define the hostname and state of the PureWeb server.

Name Description
hostname

Defines the hostname of the PureWeb server.

This value is optional, and will default to the system’s hostname, since the server attempts to determine its hostname automatically.

If system or network configuration problems prevent the server from determining its hostname, you can configure it explicitly. The specified hostname must be resolvable via either the local hosts file or the configured DNS system.

active Defines whether the PureWeb server is active and will accept incoming requests or not. When this property is set to true, the server will accept new connections if it has available sessions. Otherwise, the server will not accept new connections even if there are available sessions.
Name Description
hostname

Defines the hostname of the PureWeb server.

This value is optional, and will default to the system’s hostname, since the server attempts to determine its hostname automatically.

If system or network configuration problems prevent the server from determining its hostname, you can configure it explicitly. The specified hostname must be resolvable via either the local hosts file or the configured DNS system.

active Defines whether the PureWeb server is active and will accept incoming requests or not. When this property is set to true, the server will accept new connections if it has available sessions. Otherwise, the server will not accept new connections even if there are available sessions.

Display properties

There is only one property, display.list, found in the cluster-plugin.properties file; it is used to define the list of display devices (typically GPUs) available for use by the PureWeb server.

GPU load balancing is not supported on Windows. The recommended workaround is to create multiple VMs on top of the multi-GPU system, have each VM be dedicated to an individual GPU, and use a third-party load balancer to balance between the different VMs. For more information about load balancing options, see Multi-server environments.

Description Format
Defines the list of display devices. Each entry specifies the maximum number of client sessions allowed on a specific display device.

[max_sessions]@[display_device] where:

  • [max_sessions] is a positive integer (1..N)
  • [display_device] is the name of the associated display device, for example unix:0.0 or unix:0.1. Entries for multiple display devices must be separated by spaces.

Example

Display token form = gnu or gpu.n, where n is the GPU instance when using Quadro or ATI graphic processing units. Example: display.list=4@gpu.04@gpu.1

Permits 4 users to share the first Quadro or ATI GPU and 4 users to share the second one.

display.list=4@gpu Permits 4 users to share the available GPU resources on the system when a Quadro or ATI GPU is not being used.

Description Format Example
Defines the list of display devices. Each entry specifies the maximum number of client sessions allowed on a specific display device.

[max_sessions]@[display_device] where:

  • [max_sessions] is a positive integer (1..N)
  • [display_device] is the name of the associated display device, for example unix:0.0 or unix:0.1. Entries for multiple display devices must be separated by spaces.

Display token form = gnu or gpu.n, where n is the GPU instance when using Quadro or ATI graphic processing units. Example: display.list=4@gpu.04@gpu.1

Permits 4 users to share the first Quadro or ATI GPU and 4 users to share the second one.

display.list=4@gpu Permits 4 users to share the available GPU resources on the system when a Quadro or ATI GPU is not being used.

Server-service interaction properties

Use the properties below, found in the cluster-plugin.properties file, to create rules for application and server interactions.

Name Description
process.
response.
timeout
Defines the maximum number of seconds that an application process has to respond to a request from the server. If the application fails to respond within this timeout period, the server will consider it to be unresponsive and kill it. The default is 30 seconds.
process.
shutdown.
timeout
Defines the maximum number of seconds that an application process has to cleanly shutdown when requested by the server. If the application fails to shutdown within this timeout period, the server will consider it to be unresponsive and kill it. The default is 30 seconds.
process.
cleanup.
timeout
Defines the number of seconds between checks for inactive processes. Inactive processes will be released back to the cluster by the cleanup process. The default is 5 seconds.
Name Description
process.response.timeout Defines the maximum number of seconds that an application process has to respond to a request from the server. If the application fails to respond within this timeout period, the server will consider it to be unresponsive and kill it. The default is 30 seconds.
process.shutdown.timeout Defines the maximum number of seconds that an application process has to cleanly shutdown when requested by the server. If the application fails to shutdown within this timeout period, the server will consider it to be unresponsive and kill it. The default is 30 seconds.
process.cleanup.timeout Defines the number of seconds between checks for inactive processes. Inactive processes will be released back to the cluster by the cleanup process. The default is 5 seconds.

Client-server interaction properties

Use the properties below, found in the cluster-plugin.properties file, to define rules for client-server interactions.

Name Description
client.
activity.
timeout

Defines the maximum number of seconds that a client can consume a session with no client activity. If there is no activity from a client within this timeout the application process will be terminated and the session released to be available to other users.

The default is 30 seconds.

user.
process.
limit

Defines the maximum number of rendering processes that each user of the system may have. Requests for rendering processes above this limit will be rejected. A value of 0 may be used to specify no process limit.

The default value is 1.

Name Description
client.activity.timeout

Defines the maximum number of seconds that a client can consume a session with no client activity. If there is no activity from a client within this timeout the application process will be terminated and the session released to be available to other users.

The default is 30 seconds.

user.process.limit

Defines the maximum number of rendering processes that each user of the system may have. Requests for rendering processes above this limit will be rejected. A value of 0 may be used to specify no process limit.

The default value is 1.