Skip to content

Configuring the Jetty web server

Introduction

Funnelback includes an embedded web server which is used to provide access to the administration and search interfaces. Jetty is required for access to the Funnelback administration interface and for access to the Funnelback modern UI.

Restarting the web server

On Microsoft Windows the web server can be restarted through the Windows Services control panel (the service is called Funnelback). On Linux the service is controlled via the systemctl command. See: Starting and stopping Funnelback services

Configuration

Funnelback's embedded web server is configured automatically when Funnelback is started based on the following configuration settings contained within $SEARCH_HOME/conf/global.cfg.

  • jetty.max_heap_size and jetty.max_metaspace_size: Configures the amount of memory allocated to jetty's heap and metaspace. Note that changes to these settings are applied only when Jetty's service template is regenerated with $SEARCH_HOME/bin/setup/start_funnelback_on_boot.pl or when Funnelback is upgraded.
  • jetty.search_port: Configures the port to be used for the public (HTTP) search service
  • jetty.search_port_https: Configures the port to be used for the public (HTTPS) search service. If left blank, search will be available only over HTTP.
  • jetty.admin_port: Configures the port to be used for the administration (HTTPS) service
  • funnelback_user: The user under which the Funnelback web server should run (Unix only - on Windows the service control panel can be used to change the service user).
  • funnelback_group: The group under which the Funnelback web server should run (Unix only).
  • jetty.ssl.keymanager-password: Sets the value given to Jetty's SslContextFactory's setKeyManagerPassword method (the password for the jetty certificate key).
  • jetty.ssl.keystore-path: Sets the value given to Jetty's SslContextFactory's setKeyStorePath method (the filesystem path for the key store).
  • jetty.ssl.keystore-password: Sets the value given to Jetty's SslContextFactory's setKeyStorePassword method (the password for the key store).
  • jetty.ssl.truststore-path: Sets the value given to Jetty's SslContextFactory's setTrustStorePath method (the filesystem path for the trust store).
  • jetty.ssl.truststore-password: Sets the value given to Jetty's SslContextFactory's setTrustStorePassword method (the password for the trust store).
  • jetty.ssl.included-cipher-suites: Sets the value given to Jetty's SslContextFactory's setIncludeCipherSuites method. This is the set of cipher suites the web server may use if the web server supports the cipher suite. The value is comma separated.
  • jetty.ssl.excluded-cipher-suites: Sets the value given to Jetty's SslContextFactory's addExcludeCipherSuites method. This adds to Jetty's default set of excluded cipher suites which will not be used (even if included above). The value is comma separated.
  • jetty.ssl.included-protocols: Sets the value given to Jetty's SslContextFactory's setIncludeProtocols method. This is the set of protocols the web server may use if the web server supports the protocol. The value is comma separated.
  • jetty.ssl.excluded-protocols: Sets the value given to Jetty's SslContextFactory's addExcludeProtocols method. This is the set of protocols which must not be used, even if previously included or supported. The value is comma separated.

All the jetty.ssl.* settings above may be suffixed with .public or .admin to allow alternate settings for each individual server if desired.

Access logging customisation

Funnelback's embedded web server is configured to create access logs for the public and admin servers by default. These logs are stored in $SEARCH_HOME/web/logs/access.public.log and $SEARCH_HOME/web/logs/access.admin.log by default, and are rotated, compressed and removed automatically over time.

The specific logging configuration can be customised if required to suit different retention policies and other requirements by creating a Logback-access configuration file at $SEARCH_HOME/web/conf/jetty-access-log-logback.xml, which will be used in preference to the default config if it is provided.

The following example provdes a starting point similar to the default configuration.

<configuration>
    <!-- Send logback debugging to stderr (which ends up in the jetty error log) -->
    <statusListener class="ch.qos.logback.core.status.OnConsoleStatusListener" />

    <appender name="ACCESSLOG"
        class="ch.qos.logback.core.rolling.RollingFileAppender">
        <!-- The following filter can be used to suppress push replication polling logs -->
        <!--
        <filter class="ch.qos.logback.core.filter.EvaluatorFilter">
            <evaluator name="removePushPollingLogs">
                <expression>
                    (event.getRequestURI().contains("/commit/hash"))
                </expression>
            </evaluator>
            <onMatch>DENY</onMatch>
        </filter>
        -->

        <file>${SEARCH_HOME}/web/logs/access.${SERVER_NAME}.log</file>

        <rollingPolicy
            class="ch.qos.logback.core.rolling.SizeAndTimeBasedRollingPolicy">
            <fileNamePattern>${SEARCH_HOME}/web/logs/access.${SERVER_NAME}.%d{yyyy-MM-dd}.%i.log.gz
            </fileNamePattern>
            <maxFileSize>512MB</maxFileSize>
            <totalSizeCap>1536MB</totalSizeCap>
            <maxHistory>90</maxHistory>
        </rollingPolicy>

        <encoder>
            <!-- Pattern tokens are documented at https://logback.qos.ch/manual/layouts.html#logback-access -->
            <pattern>%h %l %u [%t] "%r" %s %b "%i{Referer}" "%i{User-Agent}"</pattern>
            <!-- The following might be a good pattern if you prefer not to record client's IP addresses
                 to avoid retaining any personally identifiable information (e.g. for GDPR compliance). -->
            <!-- <pattern>- %l %u [%t] "%r" %s %b "%i{Referer}" "%i{User-Agent}"</pattern> -->
        </encoder>
    </appender>

    <appender-ref ref="ACCESSLOG" />
</configuration>

Customisation

Further customisation is made possible during the web server start up through a Groovy hook point which can add, modify or remove Jetty server objects before they are started. The embedding Jetty tutorial provides a good starting point for learning how to work with Jetty server objects.

The Groovy script to perform any customisation should be located at $SEARCH_HOME/web/conf/customiseJettyServers.groovy, and a simple example is provided at $SEARCH_HOME/web/conf/customiseJettyServers.groovy_example.

Using a custom SSL certificate

Funnelback ships with a self-signed certificate used for the SSL endpoints (Administration interface & Search interface). A custom SSL certificate can be configured instead if required.

1. Obtain a PKCS12 bundle

Convert from PEM

The SSL certificate must be provided in a PKCS12 bundle containing both the certificate and associated private key. Converting between various certificate formats is out of the scope of this document, but as an example the following command can be used to convert a PEM certificate + private key into a PKCS12 bundle using OpenSSL (Generally available on Linux and can be downloaded on Windows):

openssl pkcs12 -export -in ssl_certificate.pem -inkey private.key -out ssl_certificate_and_key.p12 -name jetty

Enter pass phrase for private.key: <SSL_PROVIDED_PRIVATE_KEY_PASSWORD>
Enter Export Password: <PKCS12_PASSWORD>
Verifying - Enter Export Password: <PKCS12_PASSWORD>
  • SSL_PROVIDED_PRIVATE_KEY_PASSWORD is the password of the private key that was used to generate the SSL certificate with your certificate authority.
  • PKCS12_PASSWORD is a password that needs to be chosen to protect the exported PKCS12 bundle. This password will be needed in the second step below.
  • -name jetty is the identifier under which the certificate will be stored inside the bundle (a bundle can contain multiple certificates).

Get a bundle directly from your CA

If you obtained a PKCS12 bundle directly from your certificate authority, the certificate inside the bundle will be stored under a different name. You will need this name to be able to import the certificate. To list the content of a PKCS12 bundle and obtain the name, use the following command:

# Linux
$SEARCH_HOME/linbin/java/bin/keytool -list -storetype PKCS12 -keystore /path/to/bundle.p12

# Windows
%SEARCH_HOME%\wbin\java\bin\keytool.exe -list -storetype PKCS12 -keystore C:\Path\To\Bundle.p12

Enter keystore password: <SSL_PROVIDED_PRIVATE_KEY_PASSWORD>

Keystore type: PKCS12
Keystore provider: SunJSSE

Your keystore contains 1 entry

<CERTIFICATE_NAME>, Mar 3, 2017, PrivateKeyEntry,
Certificate fingerprint (SHA1): 2D:7B:77:...

The <CERTIFICATE_NAME> is the name under which the certificate is stored inside the bundle. You will need this name to import the certificate in the next step.

2. Import certificate in a Keystore

Once the bundle is ready, it needs to be imported in a Java keystore, which is what Jetty will use to access the certificate and private key. The keytool command is used to build the keystore:

# Linux
$SEARCH_HOME/linbin/java/bin/keytool -importkeystore -deststorepass <KEYSTORE_PASSWORD> -destkeypass <PRIVATE_KEY_PASSWORD> -destkeystore /path/to/new.keystore -srckeystore ssl_certificate_and_key.p12 -srcstoretype PKCS12 -srcstorepass <PKCS12_PASSWORD> -alias jetty

# Windows
%SEARCH_HOME%\wbin\java\bin\keytool.exe -importkeystore -deststorepass <KEYSTORE_PASSWORD> -destkeypass <PRIVATE_KEY_PASSWORD> -destkeystore C:\Path\To\new.keystore -srckeystore ssl_certificate_and_key.p12 -srcstoretype PKCS12 -srcstorepass <PKCS12_PASSWORD> -alias jetty
  • KEYSTORE_PASSWORD is a password that needs to be chosen to protect the keystore. Jetty will need to be configured with that password to be able to open the keystore file when it starts.
  • PRIVATE_KEY_PASSWORD is a password that needs to be chosen to protect the private key inside the keystore. Jetty will also need to be configured with this value.
  • PKCS12_PASSWORD is the password that was entered in the previous command to protect the PKCS12 bundle.
  • -alias jetty is the alias of the certificate in the PKCS12 bundle, as well as the alias under which to store the certificate + key inside the keystore. A keystore can contain multiple entries, Funnelback will use the one with the jetty alias.

Certificate imported with a different name than 'jetty'

If the certificate was stored in a different name as described previously, you must use this name for the -alias argument. The certificate will however be imported with this different name too, so the name must be changed after import with the following command:

# Linux
$SEARCH_HOME/linbin/java/bin/keytool -changealias -keystore /path/to/new.keystore -alias <CERTIFICATE_NAME> -destalias jetty -storepass <PKCS12_PASSWORD>

# Windows
%SEARCH_HOME%\wbin\java\bin\keytool.exe -changealias -keystore /path/to/new.keystore -alias <CERTIFICATE_NAME> -destalias jetty -storepass <PKCS12_PASSWORD>

Verifying the certificate import

The following command can be used to check that the certificate was correctly imported:

# Linux
$SEARCH_HOME/linbin/java/bin/keytool -list -keystore /path/to/new.keystore

# Windows
%SEARCH_HOME%\wbin\java\bin\keytool -list -keystore C:\Path/To/new.keystore

Enter keystore password: <KEYSTORE_PASSWORD>

Keystore type: JKS
Keystore provider: SUN

Your keystore contains 1 entry

jetty, Mar 3, 2016, PrivateKeyEntry,
Certificate fingerprint (SHA1): 2D:7B:77:...

There should be an entry with the jetty identifier as above. If the entry is present but under a different identifier, use the command described in the previous section to change the identifier.

3. Configure Jetty

The last step is to configure Jetty accordingly, in $SEARCH_HOME/conf/global.cfg, providing the previously entered passwords:

jetty.ssl.keystore-path=/path/to/new.keystore
jetty.ssl.keystore-password=<KEYSTORE_PASSWORD>
jetty.ssl.keymanager-password=<PRIVATE_KEY_PASSWORD>

Note that the passwords can entered in plain text or obfuscated if needed. Refer to the corresponding Jetty documentation about password obfuscation.

Jetty needs to be restarted for the changes to take effect.

See also:

top

Funnelback logo
v15.24.0