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.


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]\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 Clustered 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 Clustered 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]/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.

If the service and the server are running on the same computer, this is an internal configuration. However, if your unmanaged service and the server are deployed on different computers, you must ensure that this port is open as inbound on the server and outbound on the computer running the service.

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


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]\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 cluster, nodes and display 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.

Although some properties described in this section allow you to set up clustering to manage several nodes on the same server, clustering is not recommended. For scaling large deployments, use load balancing instead. See Multi-server environments.

Cluster properties

Use the properties below, found in the cluster-plugin.properties file, to group several servers together into a cluster defined by a specific cluster address and port.

Name Description
cluster.
enabled

Controls whether clustering is enabled. All enabled nodes with the same cluster address and port will form a cluster and balance client load across the cluster.

Clustering is deprecated. It is highly recommended to keep the default value (false) for this property.

cluster.
interface
Defines the multicast interface which will be bound to for all multicast communications. Leaving blank works, but with multi-NIC systems the bound interface will be indeterminate.
cluster.
address
Defines the multicast address shared by all nodes in a cluster. Valid addresses must be in the range 224.0.0.0 through 239.255.255.255. Nodes will only form a cluster if they have the same cluster address and port.
cluster.
port
Defines the multicast port shared by all nodes in a cluster. Valid ports must be in the range 0 through 65535 and should avoid the privileged ports with values below 1024. Nodes will only form a cluster if they have the same cluster address and port.
cluster.
status.
broadcast
Defines the number of seconds between status message broadcasts to the cluster. All nodes in a cluster send out periodic status updates notifying the other cluster nodes of their existence and current load conditions. These updates are broadcast whenever status changes occur on a node in addition to the frequency defined by this value. The standard value is 25 seconds.
cluster.
status.
timeout
Defines the number of seconds that a status message from another node is to be considered valid. The source node is marked as unresponsive if no status update is received by this timeout. This value should be set slightly higher than the status broadcast timeout to ensure that status updates are received and processed before a node is marked as unresponsive. The standard value is 30 seconds.
cluster.
response.
timeout

Defines the length of time that the PureWeb server should wait for responses from the service. Note that this property is used even if clustering is disabled.

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.

All nodes that are configured with the same cluster.address and cluster.port cooperate within a cluster and redirect requests as required to ensure that the load is distributed evenly.

application.
connection.
address
Defines the address for socket based service connections.
application.
connection.
port
Defines the port for socket-based service connections, for both managed and unmanaged services.
Name Description
cluster.enabled

Controls whether clustering is enabled. All enabled nodes with the same cluster address and port will form a cluster and balance client load across the cluster.

Clustering is deprecated. It is highly recommended to keep the default value (false) for this property.

cluster.interface Defines the multicast interface which will be bound to for all multicast communications. Leaving blank works, but with multi-NIC systems the bound interface will be indeterminate.
cluster.address Defines the multicast address shared by all nodes in a cluster. Valid addresses must be in the range 224.0.0.0 through 239.255.255.255. Nodes will only form a cluster if they have the same cluster address and port.
cluster.port Defines the multicast port shared by all nodes in a cluster. Valid ports must be in the range 0 through 65535 and should avoid the privileged ports with values below 1024. Nodes will only form a cluster if they have the same cluster address and port.
cluster.status.broadcast Defines the number of seconds between status message broadcasts to the cluster. All nodes in a cluster send out periodic status updates notifying the other cluster nodes of their existence and current load conditions. These updates are broadcast whenever status changes occur on a node in addition to the frequency defined by this value. The standard value is 25 seconds.
cluster.status.timeout Defines the number of seconds that a status message from another node is to be considered valid. The source node is marked as unresponsive if no status update is received by this timeout. This value should be set slightly higher than the status broadcast timeout to ensure that status updates are received and processed before a node is marked as unresponsive. The standard value is 30 seconds.
cluster.response.timeout

Defines the length of time that the PureWeb server should wait for responses from the service. Note that this property is used even if clustering is disabled.

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.

All nodes that are configured with the same cluster.address and cluster.port cooperate within a cluster and redirect requests as required to ensure that the load is distributed evenly.

application.connection.address Defines the address for socket based service connections.
application.connection.port Defines the port for socket-based service connections, for both managed and unmanaged services.

Node properties

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

Name Description
hostname

Defines the hostname of the node.

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.

clustered Defines whether this node is participating in the cluster defined by the cluster address and port properties. Clustered nodes may redirect requests to other nodes to ensure an even load distribution across the cluster. Unclustered nodes will not redirect requests to other nodes and may report Service Unavailable errors if they have no available sessions.
active Defines whether this node is active and will accept new connections or not. Active nodes will accept new connections if they have available sessions. Inactive nodes will not accept new connections even if they have available sessions.
Name Description
hostname

Defines the hostname of the node.

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.

clustered Defines whether this node is participating in the cluster defined by the cluster address and port properties. Clustered nodes may redirect requests to other nodes to ensure an even load distribution across the cluster. Unclustered nodes will not redirect requests to other nodes and may report Service Unavailable errors if they have no available sessions.
active Defines whether this node is active and will accept new connections or not. Active nodes will accept new connections if they have available sessions. Inactive nodes will not accept new connections even if they have available sessions.

Display properties

There is only one property,display.list, found in the cluster-plugin.properties file; it is used to define the displays (typically GPUs) used in a specific cluster.

Description Format
Defines the list of display devices available for use by this server. 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. Entries for multiple display devices must be separated by spaces.

    The format of the name varies per operating system. For example gpu.0 and gpu.1 on Windows, or unix:0.0 and unix:0.1 on Linux.

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 available for use by this server. 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. Entries for multiple display devices must be separated by spaces.

    The format of the name varies per operating system. For example gpu.0 and gpu.1 on Windows, or unix:0.0 and unix:0.1 on Linux.

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.