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.
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.
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:
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.
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:
<!-- 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>
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
To redirect all HTTP traffic to HTTP, add the following security-contraint at the the bottom of the file, just before '</web-app>':
When forcing all HTTP requests to HTTPS, the
servoy.jnlpCodebaseOverride setting needs to be the HTTPS URL (including the HTTPS Connector port number).
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.
<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>
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.
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.
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.
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.
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.
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.
1 thread per concurrent request
1 per request + 2 per client
2 Tomcat and 2 non-tomcat threads per client
2 per client
2 threads per client
1 per client
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.
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
The RMI Start port can be set through the Servoy Admin page under Network Settings > servoy.rmiStartPort. Default value is 1099
The meaning of the RMI Server Hostname setting (java.rmi.server.hostname) depends on the Connection Mode used:
If a hostname is specified, note that the hostname is resolved to an IP address on the server!
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.
10 ~ 15
Alternative value to bring down the number of open sockets, to prevent the network component form automatically closing them
When set to 0, the system default will be used
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.
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.
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.
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 .
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 reduces the amount of data send back and forth between the Servoy Application Server and the Smart Clients, thus improving performance.
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.
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.
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
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.
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.
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.
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.
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.
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.
The maximum time (in seconds) that a HTTP request is kept alive. Lower when experiencing timeout issues.
The maximum length of a single HTTP Request. Lower only when the network enforces a lower limit
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
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.
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
Empty by default. Can be set to any value if it is required to send a specific user-agent string with each HTTP request
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"
Note that the example above assume that the HTTP tunnel is already enabled. See Profiles for more info.
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.