Page tree
Skip to end of metadata
Go to start of metadata

With Java and Tomcat installed, Tomcat can now be properly configured. First, the Tomcat connectors will be configured. Depending on your configuration, some features may not be needed, such as HTTPS and IPv6. Finally, the Tomcat access log formatting and the memory settings are tweaked for usage with MyTimetable. 

Please replace $tomcat with the correct Tomcat installation folder name, such as C:\Program Files\Apache Software Foundation\Tomcat 9.0.

Configuring the Tomcat Connectors

First we configure the Tomcat Connectors, making sure the server is able to serve requests on the appropriate ports.

By default, MyTimetable uses the NIO Tomcat connector. This connector only depends on the Java JRE, and does not need extra external dependencies (like the APR connector).
  • When using SSL, put the SSL certificate into $tomcat\conf. Please see Requesting an SSL certificate for more information on obtaining an SSL certificate. The certificate needs to be in the PKCS12 (.P12/.PFX) format!
  • Open $tomcat\conf\server.xml with an appropriate editor
  • Put all <Connector /> XML elements between comments, or remove them from the file.
  • Add the following to the <Service name="Catalina"> element:

<Connector maxThreads="20" port="80" protocol="HTTP/1.1" connectionTimeout="10000" maxKeepAliveRequests="1" redirectPort="443" 
        compression="on" compressableMimeType="text/html,text/plain,text/css,application/json,application/javascript,application/x-javascript,text/xml,application/xml,application/xml+rss,text/javascript,text/calendar,application/x-font-ttf,application/vnd.ms-fontobject,image/svg+xml" />
    
<Connector maxThreads="50" port="443" protocol="HTTP/1.1" connectionTimeout="10000" keepAliveTimeout="120000" maxKeepAliveRequests="-1"
        compression="on" compressableMimeType="text/html,text/plain,text/css,application/json,application/javascript,application/x-javascript,text/xml,application/xml,application/xml+rss,text/javascript,text/calendar,application/x-font-ttf,application/vnd.ms-fontobject,image/svg+xml"
        SSLEnabled="true" scheme="https" secure="true">
	<SSLHostConfig honorCipherOrder="true" protocols="all,-SSLv2Hello"
						ciphers="TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384,TLS_DHE_RSA_WITH_AES_128_GCM_SHA256,
                			TLS_DHE_RSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256,TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA,
                			TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384,TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA,TLS_DHE_RSA_WITH_AES_128_CBC_SHA256,
                			TLS_DHE_RSA_WITH_AES_128_CBC_SHA,TLS_DHE_RSA_WITH_AES_256_CBC_SHA256,TLS_DHE_RSA_WITH_AES_256_CBC_SHA,
                			TLS_RSA_WITH_AES_128_GCM_SHA256,TLS_RSA_WITH_AES_256_GCM_SHA384,TLS_RSA_WITH_AES_128_CBC_SHA256,
                			TLS_RSA_WITH_AES_256_CBC_SHA256,TLS_RSA_WITH_AES_128_CBC_SHA,TLS_RSA_WITH_AES_256_CBC_SHA,
							SSL_RSA_WITH_3DES_EDE_CBC_SHA">
		<Certificate certificateKeystoreFile="conf/certificate.pfx" certificateKeystoreType="PKCS12" 
				certificateKeystorePassword="{KEYSTORE_PASSWORD}" />
	</SSLHostConfig>
</Connector>

Replace file names if necessary and fill in the key store password. Please omit the SSL parts if you are not using SSL. This configuration will listen on all IP addresses, including IPv6 addresses, by default.

The ciphers property tunes the SSL ciphers used with HTTPS. Please see our blog post for a discussion of the optimal SSL settings. Please note these SSL settings only work with Java 8 and a recent Tomcat release (8.5.3+). We disable keep-alive for HTTP requests (not of much use for iCal feeds) and enable them for HTTPS requests. If you are using NTLM authentication over  HTTP you should copy the keep-alive settings from the HTTPS connector.

Please note that you probably have to change the port numbers when running Tomcat on Linux, since an unprivileged user cannot open ports below 1024. See Installing Tomcat (Linux) for more information about reverse proxying requests to Tomcat.

Compression is turned on for the MIME types provided. It includes the text/calendar MIME type for the iCalendar feeds.

  • Restart Tomcat using the 'Configure Tomcat' application from the Start Menu.
  • Now, the Tomcat welcome page should be available at the following address: http://localhost/. Additionally, depending on your configuration you may also visit the page at https://localhost/ (HTTPS). The HTTPS addresses will give a certificate error, since the SSL certificate is not to be used for the local host.

Access log format

The Tomcat access log format will be changed to get more sensible logs.

  • Open $tomcat\conf\server.xml with an appropriate editor
  • Search for the Valve tag with className "org.apache.catalina.valves.AccessLogValve"
  • Change it into the following:
<Valve className="org.apache.catalina.valves.AccessLogValve" directory="logs" prefix="localhost_access_log" suffix=".txt" pattern="combined" />

Tomcat Java settings

Next, the Tomcat memory settings are tuned for usage with MyTimetable.

  • For Windows: open the 'Configure Tomcat' application from the Start Menu. For Linux: open the Tomcat init script and find the JAVA_OPTS block.
  • At the Java tab, the following memory settings should be applied:
    • Add the following setting to the Java Options input field (replace the path with the path to you Tomcat install, if necessary, and replace 'prd' with 'acc' or 'tst' where appropriate): 

      -XX:+UseConcMarkSweepGC
      -XX:NewRatio=3
      -XX:CMSInitiatingOccupancyFraction=70
      -XX:+UseCMSInitiatingOccupancyOnly
      -XX:+CMSScavengeBeforeRemark
      -XX:+HeapDumpOnOutOfMemoryError
      -Djdk.tls.ephemeralDHKeySize=2048
      -Dapplication.home=C:\Program Files\Apache Software Foundation\Tomcat 9.0\mytimetable
      -Dapplication.instance=prd
    • Add the following options when using Java 8:

      -Xloggc:C:\Program Files\Apache Software Foundation\Tomcat 9.0\logs\gc.log
      -XX:+PrintGCDetails
      -XX:+PrintGCDateStamps
      -XX:+UseGCLogFileRotation
      -XX:NumberOfGCLogFiles=5
      -XX:GCLogFileSize=5M
    • Add the following options when using Java 11:

      -Xlog:gc*:file=C:/Program Files/Apache Software Foundation/Tomcat 9.0/logs/gc.log:time,uptime:filecount=5,filesize=5M
    • Optionally, the following parameters can be added to the Java Options:
      • When using 'Syllabus Plus database merging', e.g., combining an semester 1 and semester 2 database, the following options should be added to allow (back)slashes in hostkeys:

        -Dorg.apache.tomcat.util.buf.UDecoder.ALLOW_ENCODED_SLASH=true
        -Dorg.apache.catalina.connector.CoyoteAdapter.ALLOW_BACKSLASH=true
    • Initial memory pool: 1024 MB (add -Xms1024m to the JAVA_OPTS for Linux)

    • Maximum memory pool: 1024 MB (add -Xmx1024m to the JAVA_OPTS for Linux)
    • Thread stack size: 512 KB (add -Xss512k to the JAVA_OPTS for Linux)

Removing unnecessary sample apps

Finally, we remove the welcome page.

  • Stop the Tomcat service using the 'Configure Tomcat' application from the Start Menu (Windows) or using the init script (Linux).

  • Remove the folder 'ROOT' from $tomcat\webapps
  • Start the Tomcat service again.