Child pages
  • Network Related Settings
Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 42 Next »

The Servoy Application Server exposes several services to the network it is connected to. Among other they are the following Services:

  • Launch & run Smart Clients
  • Launch & run Web Clients
  • Host the Servoy Admin page
  • Expose services of plugins, like the PDF Forms and RESTful Web Services plugins

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

Table of Contents

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.

How Smart Clients communicate with the Servoy Application server depends largely on the chosen configuration. By default the communication goes through the so-called RMI port (default port 1099), but the Servoy Application Server can be configured to tunnel all the communication over the HTTP port as well, through the so-called Tunnel.

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:

<Connector 
   port="8080" 
   protocol="HTTP/1.1" 
   maxThreads="500" 
   connectionTimeout="60000" 
   redirectPort="8443" 
   useBodyEncodingForURI="true"
/>

By altering the value of the "port" attribute, for example to 9090 or 80, the port on which the services of the Servoy Application Server are exposed can be changed. In order for the changes to gointo effect a restart of the Application Server is required.

Note that on some operating systems, like Linux of FreeBSD, bind 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:

  1. Properly enabling HTTPS requires a keystore with signed SSL certificates that must be created externally from the installation process of the Servoy Application Server
  2. In many network scenario's the Servoy Application Server is running behind a proxy or firewall that takes care of the HTTPS support. Q: IS IT "PROXY" OR "FIREWALL" OR BOTH OR SOMETHING ELSE?

If direct HTPPS support on the Servoy Application Server is required, it can be enabled in Tomcat by adding an additional connector, configured for secure access to the server.xml file located in ../application_server/server/conf.

<Connector port="8443"
   maxThreads="500" 
   connectionTimeout="60000"
   scheme="https" 
   secure="true" 
   SSLEnabled="true"
   keystoreFile="conf/keystore" 
   keystorePass="changeit"
/>

In order to create a secure HTTPS connector a keystore with a signed SSL Certificate is required. While it's possible to enable SSL withough a keystore, this is insecure and browsers will generate security warnings when accessing webpages through HTTPS. For more information on how to create a keystore, see [Creating a keystore]. The created keystore needs to be added to the Tomcat server installation that is part of the Servoy Application Server, located in ../application_server/server. It's a best practice to place the keystore in the_../application_server/server/conf/_ directory. Note that the same keystore can be used to encrypt the traffic between Smart Clients and the Servoy Application Server. See [SSL Encryption|#SSL Encryption] for more details.

In the definition of the connector above the value of the following attirbutes need to be adjusted to be correct for the supplied keystore:
* 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

Additionally, the value of the port attribute needs to be brought in sync with the value of the redirectPort attribute of the standard HTTP connector (or vise versa), as the redirectPort attribute on the HTTP connector is used to redirect HTTP traffic to HTTPS when required, see [#Enforcing HTTPS for all traffic]. The value for the port can be any value. By default the redirectPort number on the HTTP Connector is set to 8443, but any value, including the default HTTPS port 443 is possible.

Note that on some operating systems, like Linux of FreeBSD, bind a process to a port number lower than 1024 (for example the default HTTPS port 443) requires the process to run as root or under administrator privileges.

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>':

<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.

All url mappings used by Servoy can be found in the file web.xml located in ../application_server/server/webapps/ROOT/WEB-INF.

To force HTTPS only on the Servoy Admin page for example the following security-constraint ought to be used:

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

To force HTTPS on all Web Client traffic and the Servoy Admin page, but excluding it for Template access, the following security-constraints are to be used:  

  <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>

Prevent double encryption

When using the Tunnel in HTTP mode for Smart Clients with SSL turned on, using HTTPS as well would mean double encryption: the traffic withing the tunnel would be encrypted due to SSL being turned on and the network traffic would also be encrypted due to the HTTPS protocol. In order to prevent the double encryption, a conditional redirect to HTTPS can be created:

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

If HTTPS is handled outside of the Servoy Application server, the "/tunnel" URL needs to be excluded from HTTPS enforcing to prevent double encryption in case SSL is also configured.

Smart Client network 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:

  • Can all client machines access the RMI port on the Servoy Application Server?
  • Can the Servoy Application Server directly access the client machines on any port?
  • Can all client machines access the Servoy Application Server on the same IP address?
  • Are some of the client machines configured to access webpages through a proxy?

The answers to these questions could eliminate one or more of the possible connection modes, the the matrix below:

 

Direct Connection

Two-Way Socket

HTTP Tunnel

Socket Tunnel

Client machines require direct access to the Application Server's HTTP port

Unknown macro: {center}

Unknown macro: {center}

Unknown macro: {center}

Unknown macro: {center}

Client machines require direct access to the Application Server's RMI port

Unknown macro: {center}

Unknown macro: {center}

Unknown macro: {center}

Unknown macro: {center}

Application Server requires direct access to all ports on each client machine

Unknown macro: {center}

Unknown macro: {center}

Unknown macro: {center}

Unknown macro: {center}

Supports client machines with proxy configuration

Unknown macro: {center}

Unknown macro: {center}

1

Unknown macro: {center}

Unknown macro: {center}

Supports SSL Encryption

Unknown macro: {center}

Unknown macro: {center}

Unknown macro: {center}

Unknown macro: {center}

Supports compression

Unknown macro: {center}

Unknown macro: {center}

 1

Unknown macro: {center}

Unknown macro: {center}

Supports multiple IP addresses for the Application Server

Unknown macro: {center}

Unknown macro: {center}

1

Unknown macro: {center}

Unknown macro: {center}

1 Under certain circumstances Two-Way socket mode cannot initialize properly and will fall back to direct Connection mode. See Two-Way socket mode under Connection Modes below for more details

Q: IS THE OVERVIEW CORRECT? DOES DIRECT CONNECTION MODE REALLY NOT SUPPORT COMPRESSION?

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. 

Direct Connection

In Direct Connection mode Smart Clients connect to the Application Server over the configured RMI port to communicate with the application Server. Vise versa, the Application Server also connects directly to the client machine on a random port to communicate with the Smart Client.
While being the mode with the least overhead, this mode has only limited use cases. Using Direct Connection mode, all Smart Clients should be able to access the Servoy Application Server under the same IP address and access to the RMI port of the server should not be restricted. Equally important, the Servoy Application Server should also be able to connect without restrictions to any port on any client machine that will run a Smart Client. This scenario is not very likely, due to firewalls, proxies and anti-virus software.

OPEN QUESTION: ACCORDING TO SEB SSL AND COMPRESSION AREN'T SUPPORTED IN DIRECT CONNECTION MODE, ACCORDING TO JOHAN THEY ARE. WHAT IS IT?

MORE SPECIFICALLY: IF TWO-WAY SOCKET, SSL AND COMPRESSION ARE TURNED ON ON THE ADMIN PAGE AND EITHER THE USER TURNS OFF TWO-WAY SOCKET IN THE PREFERENCES OF THE SMART CLIENT OR WEBSTART SETS THE SOCKET FACTORY DUE TO PROXY CONFIG ON THE CLIENT MACHINE, SO SERVOY CANNOT INITIALIZE TWO-WAY SOCKET AND FALLS BACK TO DIRECT CONNECTION, WILL THE SMART CLIENT THEN BE ABLE TO PROPERLY COMMUNICATE WITH THE SERVER USING DIRECT CONNECTION, EVENTHOUGH SSL AND COMPRESSION ARE TURNED ON? ACCORDING TO MY TESTS IF THE USER TURNED OFF TWO-WAY SOCKET AND THE SERVER IS CONFIGURED TO RUN IN TWO-WAY SOCKET MODE WITH COMPRESSION AND SSL, THE SMART CLIENT WORKS JUST FINE. THE SMART CLIENT ALSO INDICATES IT'S RUNNING IN SSL MODE... COMPRESSION i CANNOT CHECK (DUNNO HOW TO CHECK)

Two-Way socket

Two-Way socket mode provides a more 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 connections.
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. See [#Java WebStart Proxy configuration]  for more info.

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.   

Tunnel

Servoy comes with a so-called tunnel that Smart Clients can use to connect to Application Server. The tunnel is the most robust communication mode available, at the cost of utilization of 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:

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. 

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

Direct Connection

SocketFactory.useTwoWaySocket: set to false
SocketFactory.rmiServerFactory: clear the field
SocketFactory.useSSL: set to true 1
SocketFactory.compress: set to false

In case the hostname of the server on which the Servoy Application Server runs does not resolve to an IP address that is accessible to the client machines (common on Linux systems where the hostname resolves to 127.0.0.1):
java.rmi.server.hostname: set a valid IP address of the server that the client machines can access

Two-Way socket

SocketFactory.useTwoWaySocket: set to true
SocketFactory.rmiServerFactory: clear the field
SocketFactory.useSSL: set to true 1
SocketFactory.compress: set to true

If the server on which the Servoy Application Server runs has multiple network interfaces  through which Smart CLients ought to connect:
java.rmi.server.hostname: set to the IP address of the server's loopback interface, usually 127.0.0.1

Tunnel

SocketFactory.useTwoWaySocket: set to false
SocketFactory.rmiServerFactory: set to com.servoy.j2db.server.rmi.tunnel.ServerTunnelRMISocketFactoryFactory
SocketFactory.useSSL: set to true 1
SocketFactory.compress: set to true
SocketFactory.tunnelConnectionMode: choose one of the three options 2

Q: IS THE java.rmi.server.hostname SETTING RELEVANT FOR THE TUNNEL?

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.

2: The Tunnel supports 2 modes, http and socket. These modes can either be used exclusively, by selecting either http or socket or the tunnel can be configured to allow both modes simultaneously, by selecting http&socket. When the latter is selected, [#Profiles] can be used to provide a way to Smart Clients to connect using either of the two modes.

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.

Through configuration the RMI Start Port value can be set. When the Servoy Application Server is launched it tries to bind to the specified RMI Start port. If it fails to bind to this port, it will automatically try to bind to the next port. This process will continue until the binding succeeds. 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 actually used RMI port should never be blocked by any firewall in between the Servoy Application Server and the client machines.

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 RMI Server Hostname is the IP address  

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 can be used by 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. 

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].

The created keystore needs to be added to the Servoy Application Server installation. Best practice is to place the keystore in the ../application_server/server/conf directory. In this location the keystore is then also available to the Tomcat server underlying the Servoy Application Server and thus the same certificate can also be used for serving HTTPS content (see [#Enabling HTTPS]).

After making the keystore available to the Servoy Application Server, the Servoy Application Server needs to be told where the keystore can be found and configured to use it. The relevant settings are exposed under the Network Settings on the Servoy Admin page:

  • SocketFactory.useSSL: set to true
  • 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

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.

Compression is not supported in Direct Connection mode. Q: IS THIS CORRECT?!?!

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.

Smart Client connectivity troubleshooting

TODO

Java WebStart Proxy configuration

TODO

Advanced tunnel configuration

TODO

Talk about the settings available for tunnel config and how they can be used in profiles

  • How to specify HTTP or Socket mode
  • How to tell the tunnel not to use a proxy: system.property.com.sebster.tunnel.http.client.proxyUri=* How to specify the proxy details to use
  • closeRequestOnFlush setting?
  • chunked setting?
  • com.sebster.tunnel.http.client.userAgent
  •  
Other TODO's
  • No labels