Child pages
  • Network Related Settings

Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

This chapter discusses the various configuration options in the area of network connectivity, including the ports over which the services are exposed and enabling HTTPS & SSL. The network configuration options for Smart Client connectivity comprises the majority of this chapter, as it is the most extensive.

Stoc

High Level Overview

The Servoy Application Server exposes the majority of it's services over the so-called HTTP Port (default port 8080). Through this port the Servoy Admin page, the Web Clients and plugin services are exposed to the outside world. 

...

All network communication with the Servoy Application Server can be optionally secured, by enabling HTTPS for all traffic over the HTTPS port and by enabled SSL encryption for the communication between the Smart Client and the Application Server.

Setting

...

the HTTP Port

The HTTP port, used to expose many of the services of the Servoy Application Server can be configured by editing the server.xml file located in ../application_server/server/conf. This file contains the following entry by default:

...

(warning)  Note that on some operating systems, like Linux of FreeBSD, binding a process to a port number lower than 1024 (for example the default HTTP port 80) required the process to run as root or under administrator privileges.

Enabling HTTPS

The Tomcat server that underlies the Servoy Application Server can be configured to support HTTPS. The Tomcat server that comes bundled with Servoy by default is not setup to support HTTPS, for two reasons:

...

  • keystoreFile: for example 'conf/mykeystore.ks'
    The value of this attribute needs to refer to the location and name of the keystore (either absolute or relative to the Tomcat server home directory (../application_server/server))
  • keystorePass: for example 'mypassword'
    The passPhrase of the keystore. The passPhrase is specified when creating the keystore

...

Code Block
<!-- The contents of this file will be loaded for each web application -->
<Context>

<!-- Default set of monitored resources -->
<WatchedResource>WEB-INF/web.xml</WatchedResource>

<!-- Uncomment this to disable session persistence across Tomcat restarts -->
<!--
<Manager pathname="" />
-->

<Valve className="org.apache.catalina.authenticator.BasicAuthenticator" disableProxyCaching="false"/>
<Valve className="org.apache.catalina.authenticator.NonLoginAuthenticator" disableProxyCaching="false"/>
<Valve className="org.apache.catalina.authenticator.FormAuthenticator" disableProxyCaching="false"/>
<Valve className="org.apache.catalina.authenticator.DigestAuthenticator" disableProxyCaching="false"/>
<Valve className="org.apache.catalina.authenticator.SSLAuthenticator" disableProxyCaching="false"/>
</Context>

Enforcing HTTPS

If HTTPS is enabled, it's possible within the Tomcat server underlying the Servoy Application Server to redirect specific or all incoming HTTP traffic to HTTPS by editing the web.xml file located in ../application_server/server/webapps/ROOT/web_inf

Enforcing HTTPS

...

for All Traffic

To redirect all HTTP traffic to HTTP, add the following security-contraint at the the bottom of the file, just before '</web-app>':

Code Block
<security-constraint>
    <web-resource-collection>
      <web-resource-name>Automatic SLL Forwarding</web-resource-name>
      <url-pattern>/</url-pattern>
    </web-resource-collection>
    <user-data-constraint>
      <transport-guarantee>CONFIDENTIAL</transport-guarantee>
    </user-data-constraint>
  </security-constraint>

When forcing all HTTP requests to HTTPS, the servoy.jnlpCodebaseOverride setting needs to be the HTTPS URL (including the HTTPS Connector port number).

Enforcing HTTPS

...

on Selected Traffic

Instead of redirecting all traffic to HTTPS it's also possible to redirect only specific traffic to HTTPS or exclude specific traffic. Which traffic is redirected or not is controlled by the <url-pattern> and/or <url-pattern-exclude> nodes of the <web-resource-collection> node of the security-constraint.

...

Code Block
  <security-constraint>
    <web-resource-collection>
      <web-resource-name>Unsecure access</web-resource-name>
      <url-pattern>/servoy-webclient/templates/*</url-pattern>
    </web-resource-collection>
    <user-data-constraint>
      <transport-guarantee>NONE</transport-guarantee>
    </user-data-constraint>
  </security-constraint>
  
  <security-constraint>
    <web-resource-collection>
      <web-resource-name>Automatic SLL Forwarding</web-resource-name>
      <url-pattern>/servoy-admin/*</url-pattern>
      <url-pattern>/servoy-webclient/*</url-pattern>
      <url-pattern>/servoy-webclient</url-pattern>
    </web-resource-collection>
    <user-data-constraint>
      <transport-guarantee>CONFIDENTIAL</transport-guarantee>
    </user-data-constraint>
  </security-constraint>

Smart Client Specific Configuration

The network configuration options for Smart Clients are quite extensive and which configuration to choose is largely dependent on the (different) network setups between the Servoy Application Server and the machines on which Smart Clients are launched. Determining the most optimal network configuration for Smart Client comes down to answering the following questions:

...

1 Two-Way socket mode cannot initialize properly if Java WebStart on the Client machine is configured to use a Proxy. When it fails to initialize, the Smart Client will fall back to Direct Connection mode. See 'Two-Way socket mode' under Connection Modes below for more details.

Connection Modes

The Servoy Application Server has several modes in which Smart Clients can communicate with the Application Server. Which mode is the best depends on the network setup between the Servoy Application Server and the client machines on which the Smart Client will be launched. As the Servoy Smart Client runs over both a LAN and WAN's, including over the internet, it can be that there are different network setups for different client machines. 

Available Connection Modes

Two-Way socket

Two-Way socket mode provides a robust communication mechanism between Smart Clients and the Servoy Application Server, where only the Smart Client initiates connections to the Application Server over the RMI port. This means that only the Smart Clients need to be able to access the Application Server and that the Application Server does not need to be able to connect to the client machine, like is required when using Direct Connection mode.
However, in case Java WebStart on the client machine is configured to connect through a proxy, Servoy will not be able to instantiate Two-Way socket and thus falls back to the Direct Connection mode, with the restrictions that come with Direct Connection mode. It is possible to configure Java WebStart on each client machine to not use a proxy, but this needs to be done on each individual machine and might conflict with other Java WebStart applications that do require the proxy settings. If this happens then on the client the java preferences > network settings need to be changed, so that the proxy settings are configured as 'direct connection' instead of 'use browser'. Better is to use one of the tunnels below.

Within individual Smart Clients it's possible to turn off Two-Way socket through Preferences. When the user does so, the Smart Client will start to use Direct Connection. The Smart Client will error if the network criteria for Direct Connection mode to work are not met.

Note that disabling Two-way socket mode on the Application Server is pushed to all Smart Client, but when re-enabling Two-way socket on the Application server, this setting is NOT pushed to the Smart Clients. The user needs to manually enable TwoWay socket under Preferences in the Smart Client again.   

...

Servoy comes with a so-called tunnel that Smart Clients can use to connect to Application Server. The tunnel is a more robust communication mode, at the cost of utilization of more server-side resources. For each Smart Client more memory, threads and sockets (connections) are used on the Application Server. The tunnel supports two modes, namely HTTP and Socket which can be used exclusively or mixed through the use of Profiles. Of the two tunnel modes, the HTTP mode consumes most serverside resources.

HTTP Tunnel
When using the tunnel in HTTP mode, all communication between the Smart Client and the Application Server is done using the HTTP Protocol, over the HTTP port on which the Application Server runs. The benefit of this mode is that it doesn't require that the client machines can access the Application Server on the RMI port. This can be a huge benefit in cases where it's not possible to open up access to the RMI port. When Smart Clients connect to the Application Server using the HTTP Tunnel, they will utilize threads and connections from the Tomcat application server that underlies the Servoy Application Server.

Socket Tunnel
The tunnel in Socket mode is similar to the tunnel in HTTP mode, except that the communication with the Application Server goes over the RMI port of the Application Server. This means that the RMI port of the Application Server should be accessible from all client machines that will run Smart Clients. Unlike the tunnel in HTTP mode, the tunnel in Socket mode uses server-side resources (threads & sockets (connections)) directly in Servoy, not through Tomcat. 

Resource Usage

...

per Connection Mode

The overview below indicated the difference in used resources per Connection mode. This information is provided in case tuning is required for large scale deployments. For example, by default the Tomcat HTTP/HTTPS connectors are configured to allow a maximum of 500 concurrent threads. When deploying large numbers of Smart Clients over the HTTP tunnel (possible in combination with a large number of Web Clients), it might be required to change the maximum allowed threads in the Tomcat connectors.

Connection Mode

Used Threads

Used sockets

Two-Way socket

1 thread per concurrent request

1 per request + 2 per client

HTTP Tunnel

2 Tomcat and 2 non-tomcat threads per client

2 per client

Socket Tunnel

2 threads per client

1 per client

Setting

...

the Connection Mode

All connection modes can be configured through the Servoy Admin page, under Network Settings.

...

1: SSL can also be turned off, but for security reasons it is advised to have SSL Encryption turned on when possible.See SSL Encryption for additional settings.

RMI Port

With all connection modes, except the HTTP Tunnel, the Smart Clients communicate with the Servoy Application Server over the so-called RMI port. This port needs to be accessible from all the client machines at all times, thus cannot be blocked by firewalls.

...

The RMI port number that is actually used is shown under Server Information in the Servoy Server Status on the Servoy Admin page under Servoy Server Home

Setting

...

the RMI Port

The RMI Start port can be set through the Servoy Admin page under Network Settings > servoy.rmiStartPort. Default value is 1099 

RMI Server Hostname

The meaning of the RMI Server Hostname setting (java.rmi.server.hostname) depends on the Connection Mode used:

...

(warning)  If a hostname is specified, note that the hostname is resolved to an IP address on the server!

RMI Connection Timeout

The RMI Connection timeout setting (rmi.connection.timeout) controls how long a the RMI layer will hang on to open sockets for reuse. A high value can lead to many open sockets. 

...

Value

Comment

120

Default value

10 ~ 15

Alternative value to bring down the number of open sockets, to prevent the network component form automatically closing them

0

When set to 0, the system default will be used

Ping Delay

The Ping Delay setting (ApplicationServer.pingDelay) provides a mechanism to prevent network components from closing open connections that are inactive for a while.

...

When using the HTTP Tunnel exclusively for connecting Smart Clients, the alternative HTTP tunnel KEEP_ALIVE_INTERVAL can be used instead, as this option has a lower overhead than the ApplicationServer.pingDelay setting. The ApplicationServer.pingDelay can be set to a very high number in this case.

Profiles

A Profile is a named set of settings that can be used by a Smart Client. 

Profiles are a way to allow the definition of multiple sets of configurations that are used by groups of Smart Clients. For more information on Profiles, see Profiles.

SSL Encryption

All the communication between the Servoy Application Server and the Smart Clients can be encrypted using SSL Keys and certificates. Servoy Smart Clients can only work with either a 3rd party signed certificates or without a certificate. Self signed certificates are not supported by default, but can be made to work by adding the setting SocketFactory.useTestSSL to either a Profile that is used or to the system.properties (Admin page > Admin settings > system.properties)

When SSL is enabled it will also encrypt all properties in the servoy.properties file that have a property key that contains the text 'password'. For the encryption the specified SSL certificate will be used (or a default certificate if no keystore with certificates is specified). This means that if the certificate/keystore is changed or SSL is disabled, the passwords cannot be decrypted anymore and have to be manually set again in plain text in the servoy.properties file. If the encrypted  properties are not reset manually, the Servoy Application Server will fail to launch. 

Setting Up SSL Encryption

Enabling SSL Encryption for communication between Smart Clients and the Servoy Application Server requires a keystore with a signed SSL certificate and the adjustment of a three settings on the Servoy Admin page. For more information on how to create a keystore, see Creating a keystore with a signed certificate .

...

  • SocketFactory.useSSL: set to true
  • SocketFactory.tunnelUseSSLForHttp: if the tunnel is in http or http&socket mode you can specify if http traffic should also be encrypted by the factory. If clients already only connect through HTTPS this setting can be set to false. Because the content is already encrypted by that connection done by tomcat.
  • SocketFactory.SSLKeystorePath: set to the location and name of the keystore. The path must be relative to the Servoy Application Server installation directory (../application_server/), for example server/conf/mykeystore.ks
  • SocketFactory.SSLKeystorePassphrase: Set to the passPhrase used when creating the keystore
  • SocketFactory.SSLSupportedSuites: If you need to be complaint with 'PCI certification' or something like that. Or you really don't want to enable weak cyphers between server and client. You can here specify which once you do want to support. See here what ciphers can be chosen from as an example and how tomcat can be configured also (the https part) http://www.sslshopper.com/article-how-to-disable-weak-ciphers-and-ssl-2-in-tomcat.html. This only works for the the sockets in 'http&socket' or just 'socket' configurations.

Note that SSL can also be enabled without specifying the keystore, by just setting SocketFactory.useSSL to true. This is considered insecure and should only be used for testing/demo purposes. 

Compression

Compression reduces the amount of data send back and forth between the Servoy Application Server and the Smart Clients, thus improving performance.

Enabling/Disabling Compression

The Compression setting can be administered through the Servoy Admin page, under Network Settings > SocketFactory.compress. Compression is turned on by default and should always be on. It should only be disabled when experiencing connection issues due to compression.

Running Smart Clients Behind

...

a Proxy

In many scenario's there will be proxies in between the Smart Client and the Application Server. Depending on the connection mode through which the Smart Client connects and the configuration of Java WebStart on the client machine, this will either not be an issue at all, or require some configuration or will not work.

...

(warning)  Note: up to and including Servoy 5.2.8 it is required to manually set the following system property on the Application Server to get the best possible: SocketFactory.useProxySelector=true. As of Servoy 5.2.9 and Servoy 6.0 this setting with be done by default

Advanced HTTP Tunnel Configuration

In the HTTP Tunnel connection mode, all communication between the Smart Client and the Servoy Application Server is done through the HTTP protocol and as such is susceptible to the influences of network components and/or processes that handle the HTTP traffic. Such influences can be anti-virus software, firewalls, proxies, NAT routers etc. While all these influences in general serve a goal, they can pose a challenge when trying to establish a reliable connection between the Smart Client and the Application Server. 

...

The HTTP protocol contains a mechanism to indicate the length of an HTTP request. While is not common practice to check the supplied length with the actual length and reject the request if those do not match, it can be that there are components in the network connection between the Smart Client and Application Server that do perform such a check and reject the HTTP requests if the numbers do not match. 

Additionally some components in the network might have a maximum content length that they enforce.

Default HTTP Tunnel Configuration

In everyday life, buffering is the most likely candidate to cause issues, thus by default the HTTP tunnel is configured to NOT use Chunked mode, at the cost of performance. The HTTP Tunnel is also configured by default with values for the relevant settings to prevent Connection timeout issues in most scenario's. In the area of content length enforcement, the maximum length for HTTP requests is set to a proper value. The enforcing of the actual content length being the same as the specified content length is NOT done, as the likelihood of network connections enforcing this not that great, while enabling this would result in significant performance degradation.

Custom HTTP Tunnel Configuration

The configuration of the HTTP tunnel can be altered by adding the relevant settings as system properties through the Servoy Admin page, under Servoy Server Home > Admin settings > system.properties. It's also possible to expose different configurations through Profiles.

...

Property

Default Value

Description

system.property.com.sebster.tunnel.http.client.closeRequestOnFlush

true

Whether or not to close the HTTP Request after each package of data. Default is true. While this incurs a significant overhead due to having to instantiate an HTTP request for each package of data, this does prevent buffering issues.
Besides incurring significant overhead, it also results in a large number of HTTP Requests to the Application Server, which at some point might start blocking the requests.

system.property.com.sebster.tunnel.http.client.chunked

true

Whether or not to send data packages as chunks of a larger HTTP Request. This setting has no effect if closeRequestOnFlush is set to true. Chunked mode is the preferred mode of operation, but susceptible to buffering issues.

system.property.com.sebster.tunnel.http.client.keepAliveInterval

15

The interval (in seconds) with which a little data is send into the HTTP request to prevent it from being terminated by the network due to inactivity. Lower when experiencing connection timeout issues.

system.property.com.sebster.tunnel.http.client.maxRequestAge

300

The maximum time (in seconds) that a HTTP request is kept alive. Lower when experiencing timeout issues.

system.property.com.sebster.tunnel.http.client.contentLength

2097152 b

The maximum length of a single HTTP Request. Lower only when the network enforces a lower limit

system.property.com.sebster.tunnel.http.client.strictContentLength

false

If set to true, the actual length of each HTTP request will be made to match the contentLength setting, by appending dummy data. Only set to true if the Content-Length is enforced by the network, as it incurs a significant performance penalty

system.property.com.sebster.tunnel.http.client.proxyUri

 

In case the Smart Client needs to communicate through a specific proxy and the proxy configuration cannot be done in Java WebStart, the proxy url can be set directly on the HTTP Tunnel.

system.property.com.sebster.tunnel.http.client.proxyUsername, 
com.sebster.tunnel.http.client.proxyPassword

 

Proxy credentials. If required by the proxy and not set here, the Smart Client will provide the user with a dialog to enter the credentials

system.property.com.sebster.tunnel.http.client.userAgent

 

Empty by default. Can be set to any value if it is required to send a specific user-agent string with each HTTP request

Suggested Profiles

The HTTP tunnel is already configured for most reliable connectivity, so this does not require a Profile. A relevant Profile would be the performance Profile, which basically means enabling Chunked mode, by disabling "'closeRequestOnFlush" ' 

Code Block
titleBest performance Profile
system.property.com.sebster.tunnel.http.client.CLOSE_REQUEST_ON_FLUSH=false

(warning) Note that the example above assume that the HTTP tunnel is already enabled. See Profiles for more info.

Kerebos Support

Servoy supports Kerebos authentication for Smart Clients, as Java WebStart supports Kerebos authentication. Setting up Kerebos authentication within Java WebStart on the client machine will not be described in the Servoy documentation, as it's highly specific and requires detailed knowledge of Kerebos configuration.

If Kerebos authentication support is required, the following setting sets up required authentication context within Servoy: system.property.servoy.usejaas=true. This setting can be applied through the Servoy Admin page, under Servoy Server Home > Admin settings > system system.properties or can be applied through a specific Profile.

...