Server Configuration

Web Application Server Configuration

Since the present implementation of the PTV xServer uses the Tomcat Web Application Server, there are a lot of options available.

Port Configuration

PTV xServer comes with default port settings that can often be used as they are, but sometimes may have to be changed. The following sections explain the details.

Default Port Numbers

See the table below for a list of default values.

Port Function
50000 HTTP requests
50001 (deactivated by default) Alive
50002 HTTPS requests
50003 Tomcat shutdown
50006 H2 database

Changing Default Ports

If you want or need to change the port configuration, modify the following files.

File Port Configuration
conf/server.xml

This file contains the default port configurations of the Tomcat server. Http-Port and Shutdown port need to be configured here.
Example:
Server port="50003"

Connector port="50000"

Connector port="50002"

conf/xserver.conf

This file contains the default alive port configuration. By default, the alive port is deactivated.

conf/session-management-db.xml

This file contains the configuration of the database and port used for session management.
Example:

<prop key="url">jdbc:h2:tcp://localhost:50006/./data/db/session</prop>

conf/job-management-db.xml

This file contains the configuration of the database and port used for job management.
Example:

<prop key="url">jdbc:h2:tcp://localhost:50006/./data/db/job</prop>

webapps/services/WEB-INF/web.xml

The PTV xServer comes with an additional web application, H2. Port settings for H2 within this file are:
Example:

<context-param>
	<param-name>db.tcpServer</param-name>
	<param-value>-tcpAllowOthers -tcpPort 50006</param-value>
</context-param>

Of course, you also usually need to update the configuration of all the client programs you need.

Conflicts with Ports

Port conflicts may arise with applications that let the operating system chose a port (e.g. specifying port "0" may have this effect) and thus randomly block ports that the PTV xServer would need. The cause of this conflict is usually restricted to development systems with applications that frequently start (certain virus scanners are known for this) and frequently restart the PTV xServer. Also, Windows systems now have a dynamic port range that includes the 500xx range.

Preventing Conflicts with Dynamically Assigned Ports

To adjust the dynamic port range for Windows, use the netsh shell command with administration rights:

netsh int ipv4 set dynamicportrange tcp 50200 15336
netsh int ipv4 set dynamicportrange udp 50200 15336
netsh int ipv6 set dynamicportrange tcp 50200 15336
netsh int ipv6 set dynamicportrange udp 50200 15336

To activate these settings automatically at boot time, save the following lines as file netsh.reg and run it:

Windows Registry Editor Version 5.00

[HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\Run]
"netsh-ipv4-tcp"="C:\\Windows\\system32\\netsh int ipv4 set dynamicportrange tcp 50200 15336"
"netsh-ipv4-udp"="C:\\Windows\\system32\\netsh int ipv4 set dynamicportrange udp 50200 15336"
"netsh-ipv6-tcp"="C:\\Windows\\system32\\netsh int ipv6 set dynamicportrange tcp 50200 15336"
"netsh-ipv6-udp"="C:\\Windows\\system32\\netsh int ipv6 set dynamicportrange udp 50200 15336"

To adjust the dynamic port range for Linux, modify the entries in the following files:

/proc/sys/net/ipv4/ip_local_port_range
/proc/sys/net/ipv6/ip_local_port_range

User Authentication

User authentication is one scenario where you might want to use Tomcat features. The PTV xServer is not designed to provide access control services and protection against illegal access, but there is a simple way of setting up an access control list.

You can create a configuration file: users.properties.

It consists of user=password pairs (both in plain text). If the access control file exists, incoming requests are validated against the username/password pairs. Then, callers need to either set the username/password in http request headers, or use HTTP Basic Authentication.

If you need to set up a more secured environment, you can make use of the enhanced authentication techniques that come with the web server, e.g. if you need to combine the mechanism with something like LDAP services.

Activate HTTPS

The https connector configuration is already provided in the PtvXServerService section of the server.xml configuration file. It can be enabled by simply uncommenting it and restarting the PTV xServer to apply these changes.

The configuration uses a preconfigured java keystore xserver.jks with a self signed certificate for localhost:

<Connector port="50002" protocol="org.apache.coyote.http11.Http11NioProtocol"
	   maxThreads="150" SSLEnabled="true"  disableUploadTimeout="true" compression="on" compressionMinSize="500"
		   compressibleMimeType="text/html,text/xml,text/plain,text/css,application/json,application/javascript,application/soap+xml,application/fastinfoset,application/soap+fastinfoset">
	<SSLHostConfig>
		<Certificate certificateKeystoreFile="conf/xserver.jks" type="RSA" />
	</SSLHostConfig>
</Connector>
		

In this case or using your own self-signed certificate you have to make client Java VMs approve the server certificate as described in this blog entry.

If you have a certificate signed by an official certificate authority you can import it to this keystore using the java keytool as described in How to Import a .cer Certificate Into a Java KeyStore. The keystore password is changeit and the required alias is tomcat. Please restart the PTV xServer after importing the certificate.

For further details of the Apache Tomcat HTTPS configuration see SSL/TLS Configuration How-To.

CORS Support

Related file: webapps/services/WEB-INF/web.xml

CORS (Cross Origin Resource Sharing) is activated by default for the JSONClosed JSON (JavaScript Object Notation) is an open standard format for which human-readable text is used to transmit information consisting of attribute–value pairs. It is the first-address data format used for asynchronous browser/server communication (AJAX). endpoints.

By default, all origins are allowed. Should you wish to restrict CORS access to certain origins only, or if you need to use custom request header types, you can modify the settings in the CORS section of webapps/services/WEB-INF/web.xml.

To deactivate CORS entirely, comment out the complete section; the section includes a filter-mapping with filter-name CORS.

PTV xServer Configuration File

The conf/xserver.conf file contains core parameters that control the server behavior.

Syntax

The configuration uses the HOCON notation (Human-Optimized Config Object Notation) which is a JSON superset, optimized for readability.

Here are the basic features of HOCON:

Feature Notation
comments start with # or //
keys and values
  • can be separated by : or =
  • allow unquoted strings for keys and values so "myKey" : 5 can be simplified to myKey : 5
substitutions substitutions foo : ${a.b} sets key foo to the same value as the b field in the a object
unquoted keys unquoted keys can use dot-notation for nested objects, foo.bar=42 means foo { bar : 42 }
parses duration and size settings parses duration and size settings, "512k" or "10 seconds"
multi-line string
  • is delimited by """ and uses Unicode characters unmodified
  • if it is used for a path property single backslashes within a file path are allowed

Properties

This table lists all available properties for xserver.conf.

key internal default description
core.modules.definitions default and minimum pool Each named subsection here must specify a 'services' setting which is an array containing all the services for this definition. The default definition contains a list of all included services. In addition, the setting 'moduleRunCommand' can be defined, which overwrites the global setting 'core.moduleRunCommand'.
core.modules.instances default = 1 Here you can define how many backend modules should be started for each definition. When running a huge number of modules, make sure to adjust core.moduleStartupTimeout.
core.mapPath data/map Path to the map folder. This should point to the map data folder you intend to use.
core.geocodingDataPath ${core.mapPath}/gcd (data/map/gcd) Path to the geocoding data folder. This should point to the folder with the geocoding data you intend to use. The default value is depending on the map path.
core.contentSnapshotPath data/snapshot Path to the content snapshot folder.
core.contentSnapshotCleanupEnabled false Enable or disable the automatic cleanup of unused content snapshots. Disabled by default.
core.contentSnapshotRetentionTime 7d Time to live for unused content snapshots before they get deleted by the cleanup task.
core.contentSnapshotGarbageCollectionEnabled true Enable or disable the garbage collection of invalid content snapshots. Enabled by default.
core.contentSnapshotGarbageCollectionInterval 1h Time to live for invalid content snapshots before they get deleted by the garbage collection task.
core.featureLayerPath data/flr Path to the user-created feature layer folder. They are created with the xData service. Permissions to create and write files are needed for this folder.
core.distanceMatrixPath data/dima Path to the distance matrix folder. Permissions to create and write files are needed for this folder.

Be aware that the access of distance matrices could be slowed down by using a network file system for the storage of distance matrices. Especially the list functionality could be massively retarded. As a consequence timeouts could occur. The performance of access to the contents of a distance matrix is usually acceptable because in this case file access optimizations work in particular caching.

core.distanceMatrixCleanupEnabled false Enable or disable the automatic cleanup of unused distance matrices. Disabled by default.
core.distanceMatrixRetentionTime 7d Time to live for unused distance matrices before they get deleted by the cleanup task.
core.distanceMatrixGarbageCollectionEnabled true Enable or disable the garbage collection of invalid distance matrices. Enabled by default.
core.distanceMatrixGarbageCollectionInterval 1h Time to live for invalid distance matrices before they get deleted by the garbage collection task.
core.highPerformanceRoutingNetworkPath data/hpr Path to the user-created high-performance routingClosed A route corresponds to a path of a vehicle through the underlying transport network. The main attributes of a route are the distance and the time that the vehicle travels along the path. network folder. They are created with the xData service. Networks delivered with a map are automatically found in the map folder. Permissions to create and write files are needed for this folder.
core.highPerformanceRoutingNetworkCleanupEnabled false Enable or disable the automatic cleanup of unused high-performance routing networks. Disabled by default.
core.highPerformanceRoutingNetworkRetentionTime 7d Time to live for unused high-performance routing networks before they get deleted by the cleanup task.
core.highPerformanceRoutingNetworkGarbageCollectionEnabled true Enable or disable the garbage collection of invalid high-performance routing networks. Enabled by default.
core.highPerformanceRoutingNetworkGarbageCollectionInterval 1h Time to live for invalid high-performance routing networks before they get deleted by the garbage collection task.
core.sequentialStartOfModuleProcesses false Determines whether the modules are to be started sequentially or in parallel.
core.moduleStartupTimeout 10m Maximum time for all modules to start up.
core.queueSize 25 Maximum number of permitted parallel (queued) requests per service at one time.
core.enableRequestTimeouts true Enables requests to overwrite the server side module and queuing timeouts.
core.requestQueueTimeout 60s Maximum time a request may remain in the request queue before there is a module available to process the request.
core.moduleTimeout 60s Maximum time allowed for a single engine request
core.moduleRestartRetryPeriod 300s Defines the retry period to restart a module. Restart attempts are enabled for positive values, whereas 0s means no further attempts after first try.
core.backendPingInterval 10s Time between two pings from the server to a module process.
core.backendPingTimeout 5s Time to wait for a module to answer a ping message.
core.maxTimeWithoutPing 20s Maximum time a module process may live without a ping from the server.
core.moduleRunCmd {jre}/bin/java -Dxserver.module={mod} -Xms128M -Xmx2048M -Xss16M -cp {cp} -XX:ErrorFile={log}/hs_err_pid%p.log -XX:-CreateMinidumpOnCrash -Dcatalina.base={cbd} -Djava.rmi.server.hostname=localhost -Djava.library.path={lib} -Dxserver.logdirectory={log} -Dlog4j.configurationFile=file:///{cbd}/conf/logging-module.xml {arg} {cls} {xsr} {ins} {prt} Don't touch this key if you are not sure what you are doing! The command to be executed for starting worker processes. This command string is passed to the exec-routine, replacing the following "parameters" with their corresponding values:
jre
the location of the Java installation
cp
the classpath determined by the service
cbd
the logical base directory (typically the value of $catalina.base)
log
the central log directory (defined by environment variable XSERVER2_LOG_DIRECTORY (default './logs' is set in wrapper.conf)
lib
the path where the engine libraries are searched
arg
some VM arguments taken over from the server process
cls
the class that contains the main entry point of the module
xsr
the list of services this module runs
mod
the module identification consisting of server name and instance ID
ins
the instance identifier
prt
the communication port to be used by the service
core.alivePort -1 Port on which to open a server socket after successful initialization of the server. A value of -1 indicates that no alive port should be used.
core.clusterId unknown-cluster Logical name of a cluster to be integrated into request log strings.
core.killDelayAfterCancelRequestedByUser 5s Delay after which requests will be killed, if a module instance does not react to cancel request by user.
core.killDelayAfterCancelRequestedByTimeout 5s Delay after which requests will be killed, if a module instance does not react to cancel request caused by a runtime timeout.
core.logging.logRequests exceptional Determines whether requests should be logged. If this option is set, incoming responses will be written to the log file. This option is useful for debugging or recording issues. Can be one of true, false, exceptional, or fatal. See Logging configuration for details.
core.logging.logResponses false Determines whether responses should be logged. Can be one of true, false or exceptional. See Logging configuration for details.
core.logging.selectedRequestHeaders - List of HTTP request header names that can be logged by an extended logging configuration. See How to extend logging for HTTP request headers in Logging configuration for details.
core.jobs.jobQueueTimeout -1 Maximum time a single asynchronous job may remain in the request queue before there is a module available to process the job. (-1 disables the timeout).
core.jobs.jobModuleTimeout -1 Maximum time allowed for a single asynchronous job. -1 means no timeout.
core.jobs.resultRetentionTime 7d Time to live for unfetched persistent job results before the system can delete entries from the persistent store. Default is 7 days.
core.jobs.fetchedResultRetentionTime 1h Time to live for fetched persistent job results before the system can delete entries from the persistent store. Default is 1 hour.
core.jobs.zombieRetentionTime 1d Time to live for zombies of jobs before the system can delete entries from the persistent store. Default is one day.
core.security.moduleSpecificMonitoringRequests false Activates the option to redirect requests to dedicated backend instance via http header.
core.security.adminAccessWhitelist
0.0.0.0/0, ::/0 Specifies a list of host names, IP addresses, and IP ranges in CIDR notation which may access the xServer as an admin. Admins will see the full dashboard, while other users have a restricted access. For example the Status Monitor or the Metrics Page is only visible for admins. Default allows all IP addresses. The recommendation is to restrict this to your local network. For example adminAccessWhitelist=127.0.0.1, ::1, 172.0.0.0/8, 192.168.0.0/16, fc00::/7. If a host name could not be resolved or the IP address is not syntactically correct, the xServer will shut down immediately.
core.security.externalResourcesAccessWhitelist
- Specifies a list of host names, IP addresses, and IP ranges in CIDR notation from which the xServer may download resources such as icons and profilesClosed A profile is a collection of parameters used to configure the request. Full profiles consist of a number of specialized sub-profiles like the VehicleProfile which describes the properties of a vehicle.. For example externalResourcesAccessWhitelist=127.0.0.1, ::1, 172.0.0.0/8, 192.168.0.0/16, fc00::/7. If a host name could not be resolved or the IP address is not syntactically correct, the xServer will shut down immediately. Default disallows all IP addresses, i.e. access to external resources is not possible.
core.license.licenseFilePath - Path to license file.
core.license.floatingLicenseServerAddress - URL to the license server.
core.scripting.scriptCheckInterval 5s Time interval to check server side scripts for changes. -1 disables the check.
core.hostedVersions - This subsection specifies which API versions of PTV xServer should be hosted.
core.hostedVersions.default [current version, head, experimental] This entry lists all API versions that should be hosted for xRuntime and all configured services. This parameter exists since version 2.6.
core.hostedVersions.[service] - This entry overwrites the API versions which are configured with core.hostedVersions.default. It specifies all API versions that should be hosted for the corresponding service.
core.contentupdates.contentUpdateService.url http://localhost:50100/contentupdateservice URL locating the Content Update Service (CUS).
core.contentupdates.contentUpdateService.username - Username used to establish a connection to the Content Update Service (CUS).
core.contentupdates.contentUpdateService.password - Password used to establish a connection to the Content Update Service (CUS).
core.contentupdates.broker.url http://localhost:50108 URL locating the broker of the Content Update Service (CUS).
core.contentupdates.broker.username - Username used to establish a connection to the broker of the Content Update Service (CUS).
core.contentupdates.broker.password - Password used to establish a connection to the broker of the Content Update Service (CUS).
core.contentupdates.contentUpdatePath data/content-update Relative path to the xServer base directory at which the updated content is stored.
core.contentupdates.updateMode continuous Determines how content updates are downloaded and installed. Can either be set to 'continuous', i. e. all updates are downloaded and installed automatically or 'onDemand', which means that updates have to be triggered via xruntime method 'triggerContentUpdate'. This mode must comply with the mode of the Content Update Service (CUS) that is used (cf. Using Content Update Service).
core.contentupdates.content.featureLayer.enabled false Determines if content updates are enabled for Feature Layers. If enabled, a connection to the configured Content Update Service (CUS) is established.
core.contentupdates.content.featureLayer.themes - List of Feature Layer themes that should be requested. At least one theme is mandatory, otherwise no Feature Layers will be downloaded.
core.contentupdates.content.featureLayer.providerNames - List of Feature Layer provider names that should be requested. At least one provider name is mandatory, otherwise no Feature Layers will be downloaded.
core.contentupdates.content.featureLayer.countries - List of country codes (ISO 3166-1/ISO 3166-2) acting as a filter if present. If the list is empty, all available countries for the current map will be requested. Please note that subdivisions and continent codes can also be used (cf. country codes).
core.contentupdates.content.basicToll.enabled false Determines if content updates are enabled for basic toll data. Please note that basic toll data is only available for Europe. If enabled, a connection to the configured Content Update Service (CUS) is established.
core.contentupdates.content.basicToll.productName PTV_xServer Product name to use as filter criterion to request basic toll data. In most cases, the default value should be correct.
core.contentupdates.content.basicToll.mapName The display name of the used map if it can be determined automatically.

Name of the map that is used as filter criterion to request basic toll data. Only Europe or World map names are supported. If the default value does not work for the used map, a corresponding Europe or World map name has to be configured.

core.contentupdates.content.detailedToll.enabled false Determines if content updates are enabled for detailed toll data. If enabled, a connection to the configured Content Update Service (CUS) is established.
core.contentupdates.content.detailedToll.providerNames - List of toll provider names that should be requested. At least one provider name is mandatory, otherwise no detailed toll will be downloaded.
core.contentupdates.content.detailedToll.countries - List of country codes (ISO 3166-1/ISO 3166-2) acting as a filter if present. If the list is empty, all available countries for the current map will be requested. Please note that subdivisions and continent codes can also be used (cf. country codes).
core.contentupdates.content.detailedToll.productName PTV_xServer Product name to use as filter criterion to request detailed toll data. In most cases, the default value should be correct.
core.session.retentionTime 60m Durability of session storage data. The session storage can currently be used for ChangeToursRequests and ToursInExecutionRequests in the xtour service (cf. Session Storage).
core.session.cleanupInterval 30m Interval in which a cleanup job for session storage data is started. The cleanup job deletes all data that exceeds the retentionTime (cf. Session Storage).
core.cacheControl.maximumAge 86400 Maximum age of RESTClosed REST (Representational State Transfer) represents a World Wide Web paradigm, consisting of constraints to the design of components which results in a better performance and maintainability. requests in the client's cache (cf. Cache Configuration).
core.tollOptions.useDetailedToll true This configuration parameter sets the default data source for toll price calculation. The parameter can be overwritten in the tollOptions of a route request or in the distanceMatrixOptions of a distance matrix calculation request.
The default value is set to true, which means that toll prices are calculated with detailed toll data. You can choose to switch to basic toll data if the detailed toll data are not completely available in your region or on your map.
The parameter might be removed in the future.
xmap.fontPath data/fonts Path of the directory containing all fonts needed for rendering labels or other texts in a map. The default value refers to the predefined directory existing after xServer installation.
xmap.bitmapPath data/bitmaps Path of the directory containing all bitmaps needed for rendering various objects in a map. The default value refers to the predefined directory existing after xServer installation.
xmap.defaultIcon default.png Name of the default icon which will be displayed when the configured icon is not present.
xmap.groupIcon group.png Name of the group icon which is displayed when several icons would overlap on the map image.
xroute.reachability.maximumDistanceHorizon
200000 When executing either of calculateReachableAreas request or calculateReachableLocations request, the distance-based horizon is limited to this value due to performance reasons. The default value of 200 km should be sufficient for a calculation within the timeout of a synchronous request. Increasing this value might cause synchronous requests to be aborted, use asynchronous requests instead.
xroute.reachability.maximumTravelTimeHorizon 7200 When executing either of calculateReachableAreas request or calculateReachableLocations request, the travel-time-based horizon is limited to this value due to performance reasons. The default value of 2 hours should be sufficient for a calculation within the timeout of a synchronous request. Increasing this value might cause synchronous requests to be aborted, use asynchronous requests instead.
xdima.get.maximumNumberOfRelations 250000 This configuration parameter sets the maximum allowed number of relations that can be retrieved from or provided to a distance matrix via one of the following requests : CreateAndGetDistanceMatrixRequest, ImportDistanceMatrixRequest, GetDistanceMatrixByLocationsRequest or GetDistanceMatrixByRelationsRequest.
Note: When increasing this value it may be necessary to increase the Java heap memory settings of the server and modules to ensure stability.
xtour.maxNumberOfThreads 1 Maximum number of threads to be used by the xtour service. The default is a single thread service. Increasing the number of maximum threads can lead to performance improvements because the xtour service can execute certain tasks in parallel. Notice that this parameter is just an upper bound on the number of threads, it is not assured that the xtour service uses this maximum number (e.g. if there are not that many threads available on your machine).
xcluster.solverType Gurobi Mathematical solver to use in xcluster operations. By default Gurobi is used. The other possible option is to use CBC. Unless you have a good reason to use CBC, it is highly recommended to use Gurobi as it is superior to CBC in terms of performance and solution quality. Also consider Configuring Optimization Solver for more insight on this.
xdata.segments.maximumNumberOfSegments 5000 Maximum number of segments returned by getSegments operations. Increasing this value can significantly affect the performance of related operations.
xdata.binaryFeatureLayer.maximumNumberOfSegments 20000 Maximum number of segments allowed when creating a binary feature layer. Increasing this value can significantly affect the performance of related operations.