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.

Changing Default Ports

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

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

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

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

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

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 routing 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 profiles 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 REST 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.