Administrator's Guide > Installation and Configuration > Server Configuration

Server Configuration

Web Application Server Configuration

Since the present implementation of the PTV xServer use the Tomcat Web Application Server, there are a lot of options available. However, it is highly recommended not to touch most of these settings, unless you are an expert and know how PTV xServer interact with the Tomcat server on a technical level.

Port Configuration

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

Default Port Numbering Schema

Default PTV xServer ports follow a numbering schema. All PTV xServer have the prefix 500, followed by an PTV xServer-specific digit and a functional digit. See the tables below for a list of default values.

Port	Server
5000x	PTV xServer bundle
5001x	PTV xMap Server
5002x	PTV xLocate Server
5003x	PTV xRoute Server
5004x	PTV xMapmatch Server
5005x	PTV xLoad Server
5006x	PTV xTerritory Server
5007x	PTV xDima Server
5008x	PTV xCluster Server
5009x	PTV xTour Server

Port	Function
50xx0	HTTP requests
50xx1	Alive
50xx2	HTTPS requests
50xx3	Tomcat shutdown
50xx6	Derby database (not all PTV xServer)

Changing Default Ports

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

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="50033"

Connector port="50030"

Connector port="50032"
conf/xserver.properties

This file contains the default alive port configuration. By default, the alive port is deactivated.
conf/<xserver>.properties

This server-specific file defines - depending on the server - database ports.
conf/wrapper.conf

This file defines several ports as runtime properties, e.g. -Dhttp.port. Please make sure to change these values according to the server.xml-settings.

Example:
```
wrapper.java.additional.11=-Dport.http=50030 wrapper.java.additional.12=-Dport.xml=50034
```

conf/default-geodatasource.xml and other geodata .xml files

All geodatasource files contain port numbers for xsd schema locations and jdbc derby connections.

Example:

<GeoDatasource majorVersion="1" minorVersion="0" ..... 
  http://localhost:50030/xroute/schema/1.0/GeoDatasource.xsd"> 
<Datasource driver="org.apache.derby.jdbc.ClientDriver" 
  url="jdbc:derby://localhost:50036/poi" user="POI" password="POI"/>

conf/job-management-db.xml

This file contains the configuration of the database and port used for job management.
Example:
```
<property name="jdbcUrl" value="jdbc:derby://localhost:50036/job" />
```
webapps/derby/WEB-INF/web.xml

Most PTV xServer come with an additional web application, Derby. Port settings for Derby within this file are:
Example:
```
<init-param>
  <param-name>portNumber</param-name>
  <param-value>50036</param-value>
</init-param>
```

conf/wms.properties

If you are using PTV xMap Server together with the WMS plugin, you have to adjust the port settings for WMS:

Example:

xmap-default.description=Get a standard map from the xMap server

xmap-default.url=http://localhost:50010/xmap/ws/XMap
...
xmap-plain.url=http://localhost:50010/xmap/ws/XMap

conf/ajaxmaps.properties

If you are using PTV xMap Server together with the ajaxmaps plugin, you have to adjust the port settings for ajaxmaps:

Example:
```
mapServerURL=http://127.0.0.1:50010/xmap/ws/XMap
...
allowedRemoteURLPrefixes=http://localhost:50010
```

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

Preventing Conflicts with Dynamically Assigned 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 PTV xServer would need. This conflict cause is usually restricted to development systems with frequently starting applications (certain virus scanners are known for this) and frequently restarted PTV xServer. Also, Windows systems meanwhile have a dynamic port range that includes the 500xx range.

There are two good options to prevent this type of port conflicts: Either change PTV xServer port defaults as documented above, or adjust the dynamic port range of your system.

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 with HTTP Basic Authentication

User authentication is one scenario where you might want to use Tomcat features. PTV xServer are not designed to provide access control services and protection against illegal access. PTV xServer has two ways to configure user authentication with HTTP Basic Authentication:

The simple way with a file named users.properties:
To set up an access control list: you can create a configuration file named users.properties in the conf directory of the server. The file 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 username/password in http request headers.
Using the standard Tomcat features
see the section below.

Activate HTTP Basic Authentication with standard Tomcat features

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

The configuration is already provided in the xServer files conf/server.xmlconf/tomcat-users.xml and webapps/<modulename>/WEB-INF/web.xml.

Caution: The configuration is only a sample and is not designed for large-scale production use.

To activate change the following files:

conf/server.xml

Remove the comments around

<GlobalNamingResources>
    <Resource name="UserDatabase" auth="Container"
          type="org.apache.catalina.UserDatabase"
          description="User database that can be updated and saved"
          factory="org.apache.catalina.users.MemoryUserDatabaseFactory"
          pathname="conf/tomcat-users.xml" />
</GlobalNamingResources>

to activate the UserDatabase defined in conf/tomcat-users.xml.

Activate the UserDatabaseRealm inside the <Engine> element by removing the elements around the code block

<Realm className="org.apache.catalina.realm.LockOutRealm">
<Realm className="org.apache.catalina.realm.UserDatabaseRealm"
       resourceName="UserDatabase"/>
</Realm>

conf/tomcat-users.xml
Activate the <tomcat-users> element with the sample user "tomcat" which has the role "tomcat"

<tomcat-users>
  <role rolename="tomcat"/>
  <user username="tomcat" password="tomcat" roles="tomcat"/>
</tomcat-users>

webapps/<modulename>/WEB-INF/web.xml
Activate the security block by removing the comments around the elements <security-role>,<security-constraint> and <login-config>:

<security-role>
    <description>tomcat User which is defined in XSERVER/conf/tomcat-user.xml</description>
    <role-name>tomcat</role-name>
</security-role>
<security-constraint>
    <web-resource-collection>
        <web-resource-name>Enabled Soap Service and enabled Rest Service</web-resource-name>
        <url-pattern>/ws/*</url-pattern> 
        <url-pattern>/rs/*</url-pattern>
        <http-method>GET</http-method>
        <http-method>POST</http-method>
    </web-resource-collection>
    <auth-constraint>
        <role-name>tomcat</role-name>
    </auth-constraint>
    <user-data-constraint>
        <description>transport-guarantee can be CONFIDENTIAL, INTEGRAL, or NONE</description>
        <transport-guarantee>NONE</transport-guarantee>
    </user-data-constraint>
</security-constraint>
<login-config>
    <auth-method>BASIC</auth-method>
    <realm-name>UserDatabase</realm-name>
</login-config>

The <url-pattern> element describes which element should have the security constraint. /ws/* enables the security-constraints for the Soap Service, /rs/* for the Rest Service.

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.

Deactivate SOAP/JSON Services

Both SOAP and JSON services are activated by default. Each service can be deactivated separately if needed. To deactivate a service, comment out the complete SOAP/JSON sections in webapps/<modulename>/WEB-INF/web.xml; each section includes a servlet element, a servlet-mapping element and one or two filter-mapping elements.

CORS Support

CORS (Cross Origin Resource Sharing) is activated by default for the JSON endpoints.

By default, all origins are allowed. Should you wish to restrict CORS access to certain origins only, or need to use custom request header types, you can modify the settings in the CORS section of webapps/<modulename>/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 Properties File

The xserver.properties file contains core parameters that control the server behaviour. Typically, you will not need to change any of those since they have been optimised for best reliability and performance.

key	default	description
separateModuleProcess	true	Determines whether the modules are to be run in the same process as the server, or if a separate process should be started for the module.
sequentialStartOfModuleProcesses	false	Determines whether the modules are to be started sequentially or in parallel.
requestQueueSize	10	maximum number of allowed parallel (queued) requests within the server at one time.
memoryStatsInterval	1000	update memory info every <n> ms (-1 means no memory logging)
moduleRestartRetryPeriod	0	Specifies the retry period in seconds to restart a module. 0 means no further restart attempts after first try. A reasonable value is, for example, 300 seconds.
failOnMissingCoordFormat	true	fail if no coordinate format is specified
defaultCoordFormat	PTV_MERCATOR	default coordinate format if none is specified
failOnIllegalProfile	false	fail if a non-existing profile is requested
backendPingInterval	5000	the time in milliseconds between two pings from the server to a module process
maxTimeWithoutPing	30000	the maximum number of milliseconds, a module process may live without a ping from the server
coldStartGracePeriod	60000	Time to wait after cold start before the pinging mechanism is established. Set this to a higher value to avoid issues with slow database initialisations or other I/O dependencies.
httpCheckInitialDelay	30000	the initial delay before subsequently checking whether the http-port is accessible
httpCheckInterval	10000	the interval between two http-port checks
alivePort	-1	the port to open a server socket after successful initialisation of the module. A value of -1 indicates that no alive port should be used
addHostInfoToResponse	true	determines if host information should be added to the response headers. If this option is set, the response will contain headers identifying the server host. This identification includes the name and the enumeration of all non-loopback adapters using their according IP addresses.
logRequests	fatal	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.
logResponses	false	determines whether responses should be logged. Can be one of true, false or exceptional.
clusterId	unknown-cluster	logical name of a cluster to be integrated into request log strings
snippetLoader.allowedPrefix	/profiles/	If the value of the CallerContext property "ProfileXMLSnippet" starts with "/", it is interpreted as a relative URI with respect to the base URI. In this case the snippet is downloaded via HTTP and its content is used like a normal XML snippet. The base URI is determined from the first incoming request or can be set in the Wrapper Configuration. The property snippetLoader.allowedPrefix restricts the allowed URIs to the given prefix and must begin with a '/' character.
snippetLoader.cacheSize	50	Cache size of the snippet download cache. The cache is a simple LRU cache. Entries have an unlimited lifetime. If the value is <= 0, the cache is disabled.
killDelayAfterCancelRequestedByUser	5000	delay in ms after which request will be killed, if a module instance does not react to cancel request by user
killDelayAfterCancelRequestedByTimeout	5000	delay in ms after which request will be killed, if a module instance does not react to cancel request caused by a runtime timeout
jobResultRetentionTime	604800000	Time to live for unfetched persistent job results before the system may delete entries from the persistent store. Values are given in ms. Default is one week.
fetchedJobResultRetentionTime	3600000	Time to live for fetched persistent job results before the system may delete entries from the persistent store. Values are given in ms. Default is 1 hour.
zombieJobRetentionTime	86400000	Time to live for zombies of jobs before the system may delete entries from the persistent store. Values are given in ms. Default is one day.
statisticsLogPeriod	300	Specifies how often the server should write statistic information to the server's log file (in seconds). The default is 300 seconds (= 5 minutes). The statistic log contains information about memory, successful and failed requests, uptime and module restarts.
responseGeometrySignificantFigures	11	The number of significant figures for response geometries. The default is 11, which ensures adequate accuracy for earth coordinates. Reasonable values last from 17 to 8.
adminAccessWhitelist	0.0.0.0/0, ::/0	Specifies a list of IPs / IP ranges which may access the PTV xServer as an administrator. Default allows any IP. 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`
proxy	-	Specifies the IP of a proxy which is automatically excluded from the adminAccessWhitelist. This is recommended as they potentially hide Internet addresses with a site local address. By default the proxy is not set.
proxyControlsWebAdminAccess	false	If set to true requests coming from the proxy are checked for the string `webadmin` as part of the `features` http header. This allows user authorisation by a middleware proxy.