2. Maintenance

2.1. Moving database server

Click here for detailed steps

Use the following step-by-step instructions if you are moving the database used by TrustView:

Step 1

TrustView uses Apache Tomcat to host the application. On the Embedded version of TrustView, the database connection is configured in the trustview.groovy file, typically located here:

Directory path (Embedded version)

C:\Program Files\TrustView-Embedded\tomcat\conf\trustview.groovy

Tip

If you are unable to locate the directory, contact our Support for assistance.

Important

If you are still using the Standalone version of TrustView, see the note under Step 2 below for where to find the equivalent files instead.

Step 2

The trustview.groovy file contains the JDBC URL for the database connection:

JDBC URL example

dataSource {
...
url = "jdbc:jtds:sqlserver://dbhost:1433;databaseName=trustviewdb;useNTLMv2=true;domain=CONTOSO"
...
}

Now simply change the dbhost to the new database host and save the file.

Important

A JNDI-based datasource is also supported on the Embedded version, but there is no context.xml file to edit - it is configured instead with embedded.server.datasource.jndi.* properties in trustview.properties or trustview.groovy. The factory class is embedded.server.datasource.jndi.factory = "org.apache.tomcat.jdbc.pool.DataSourceFactory" (Tomcat’s own JDBC connection pool), and the usual connection properties are set the same way, e.g. embedded.server.datasource.jndi.url, embedded.server.datasource.jndi.username, embedded.server.datasource.jndi.password and embedded.server.datasource.jndi.driverClassName, alongside pool-tuning properties such as embedded.server.datasource.jndi.maxTotal, minIdle and validationQuery.

If you are still using the Standalone version of TrustView, the database connection URL can be located in one of two places instead, depending on whether your installation of TrustView is configured to use JNDI or not:

• If your installation is using JNDI for database configuration, the file Tomcat-install-dir/conf/context.xml contains the JDBC URL in the URL attribute of the Resource element, e.g.:

  JDBC URL example (JNDI case, Standalone version)

  <Resource
  name="jdbc/trustview"
  ...
  url="jdbc:jtds:sqlserver://dbhost:1433;databaseName=trustviewdb;useNTLMv2=true;domain=CONTOSO"
  ...
  />
  

• If your installation is not using JNDI for the database resource, the file Tomcat-install-dir/lib/TrustView.groovy contains the JDBC URL for the database connection instead, in the same dataSource { url = ... } form shown above.

Either way, simply change the dbhost to the new database host and save the file.

Step 3

If using a SQL Express database, the instance name needs to be added.

JDBC URL example for SQL Express database

url="jdbc:jtds:sqlserver://dbhost:1433;databaseName=trustviewdb;instance=SQLEXPRESS;user=dbuser"

See Building the connection URL for more information on building case-specific connection URLs.

Step 4

Finally, restart the Embedded TrustView service for the change to take effect (or, if you are still using the Standalone version, restart the Apache Tomcat service instead). TrustView is now connecting to the database on the new database host.

2.2. Set up Microsoft JDBC Driver

Click here for detailed steps

To use the Microsoft JDBC drivers for the database connection, follow these steps:

Important

These steps describe the context.xml-based JNDI setup used on the Standalone version of TrustView. On the Embedded version there is no context.xml file; instead, place the Microsoft JDBC driver .jar file directly in C:\Program Files\TrustView-Embedded\tomcat\lib - it is automatically bundled into the application on every start, the same way a Standalone Tomcat picks it up from its own lib folder. Then set embedded.server.datasource.jndi.driverClassName = "com.microsoft.sqlserver.jdbc.SQLServerDriver" (already the default) and the rest of the embedded.server.datasource.jndi.* connection properties in trustview.properties or trustview.groovy, instead of editing context.xml.

Step 1

Download the newest version of the drivers from Microsoft: Download Microsoft JDBC Driver.

Step 2

Copy the file mssql-jdbc_auth-<version>.x64.dll to C:\Program Files\Eclipse Adoptium\jdk-<version>\bin

Copy the file mssql-jdbc-<version>.jre8.jar to C:\Program Files\Apache Software Foundation\Tomcat X.X_TrustView\lib

Important

The directories may differ depending on where your TrustView and Java installation folders are placed. The Java used may also not be Eclipse Adoptium, but another version, and therefore the directory may be named differently, but the jre and bin folders should still be present.

Step 3

Replace the line containing the default Java JDBC driver class in the context.xml file, located in the conf folder, with the Microsoft one:

Driver class to use for Microsoft JDBC drivers

driverClassName="com.microsoft.sqlserver.jdbc.SQLServerDriver"

Step 4

Configure the JDBC URL (or adjust it, if already configured with the default Java JDBC driver) in the context.xml file:

JDBC URL example for the SQL database and the new Microsoft JDBC drivers

url="jdbc:sqlserver://dbhost:1433;databaseName=trustviewdb;integratedSecurity=true;authenticationScheme=NTLM;user=dbuser;password=dbpassword"

Step 5

Finally, the Apache Tomcat service must be restarted for the changes to take effect. TrustView will now be connecting to the database on the database host with the Microsoft JDBC drivers.

Troubleshooting

If the following error is seen in the TrustView logfile:

Error message that may occur during the establishment of the database connection

Caused by: com.microsoft.sqlserver.jdbc.SQLServerException: The driver could not establish a secure connection to SQL Server by using Secure Sockets Layer (SSL) encryption

The following options should be added to the JDBC URL:

Options to add to the JDBC URL

encrypt=true;trustServerCertificate=true

In some instances, it may also be necessary to remove the user=dbuser and password=dbpassword from the JDBC URL, if it has trouble connecting with the Microsoft JDBC drivers.

2.3. Using Azure Authentication for database

Click here for detailed steps

To use Azure Authentication for the connection between TrustView and your database, follow these steps:

Important

These steps describe the context.xml-based JNDI setup used on the Standalone version of TrustView. On the Embedded version there is no context.xml file; the same embedded.server.datasource.jndi.* properties described earlier on this page apply instead, and a .jar file is added the same way, by placing it in C:\Program Files\TrustView-Embedded\tomcat\lib. Two of the libraries listed in Step 3 below - msal4j and nimbus-jose-jwt - are already bundled with the Embedded application, so you likely only need to add the Microsoft JDBC driver itself; if the connection still fails to load a class after that, contact our Support to confirm which additional libraries your Embedded version needs.

Step 1

Take a look at the required file versions, depending on your Microsoft JDBC drivers here.

Step 2

Adjust your JDBC URL found in the context.xml file of the conf directory to include the following properties:

• authentication=ActiveDirectoryPassword

• encrypt=true (Encryption is mandatory for Azure)

• [Optional] loginTimeout=30 (This property can be used and adjusted to ensure the connection is being established if the network is slow)

Step 3

Add the following .jar files to the lib directory, as they are the minimum requirement for Azure Authentication:

• mssql-jdbc-12.x.x.jre8.jar

• msal4j-<version>.jar

• nimbus-jose-jwt-<version>.jar

• oauth2-oidc-sdk-<version>.jar

• jackson-annotations-<version>.jar

• jackson-core-<version>.jar

• jackson-databind-<version>.jar

Tip

The files can be found and downloaded from here.

Once the files have been placed, restart the Tomcat service to take all the new changes into account.

2.4. How to use gMSA for the database

Click here for detailed steps

If you want to use gMSA (Group Managed Service Accounts) for the TrustView database connection, you can do so by setting up such an account (see gMSA overview).

Important

These steps describe the context.xml-based JNDI setup used on the Standalone version of TrustView. On the Embedded version there is no context.xml file; set embedded.server.datasource.jndi.auth and the connection URL’s authenticationScheme the same way, in trustview.properties or trustview.groovy instead, and remove the embedded.server.datasource.jndi.username and embedded.server.datasource.jndi.password properties rather than the context.xml lines. The Windows service identity (Log On This account) is configured the same way for both versions, since it is a Windows service setting rather than a TrustView one.

Next you need to attach it to the TrustView service by adding it under Log On This account under Properties of the service.

Then you need to update the JDBC URL found in the context.xml file in the conf directory.

Remove the lines with Username and Password from the context.xml file, as they are not necessary with a gMSA.

JDBC URL example with a gMSA user

url="jdbc:sqlserver://dbhost:1433;databaseName=trustviewdb;integratedSecurity=true;authenticationScheme=NativeAuthentication;encrypt=true;trustServerCertificate=true"

Note

Either authenticationScheme=NativeAuthentication or authenticationScheme=JavaKerberos can be used. Just select one of the methods.

2.5. Add database performance logging

Click here for detailed steps

Use the following step-by-step instructions if you need to monitor the performance of the database used by TrustView:

Step 1

Locate the trustview.groovy file in the TrustView installation directory, typically:

Directory path to the Embedded TrustView configuration file

 C:\Program Files\TrustView-Embedded\tomcat\conf\trustview.groovy

Add and enable the generate_statistics setting to the file:

Example of enabling additional logging in the TrustView configuration file

hibernate {
    ...
        generate_statistics = true
    ...
}

Important

If you are still using the Standalone version of TrustView, the configuration file is named TrustView.groovy and found here instead:

Directory path to the Standalone TrustView configuration file

 C:\Program Files\Apache Software Foundation\Tomcat X.X_TrustView\lib\TrustView.groovy

Step 2a (logback.xml)

If you are using xml-based logging (logback.xml), then locate the file and add the following appender. On the Embedded version of TrustView it is typically found here:

Directory path of the logback.xml logging configuration file (Embedded version)

 C:\Program Files\TrustView-Embedded\tomcat\conf\logback.xml

Tip

If you are still using the Standalone version of TrustView, it is instead found at C:\Program Files\Apache Software Foundation\Tomcat X.X_TrustView\conf\logback.xml.

Example of how to add the appender in the logback.xml configuration file

<appender name="DB_PERFORMANCE" class="ch.qos.logback.core.rolling.RollingFileAppender">
    <rollingPolicy class="ch.qos.logback.core.rolling.TimeBasedRollingPolicy">
        <fileNamePattern>${LOG_ROOT}/trustview-db-%d{yyyy-MM-dd}.log</fileNamePattern>
    </rollingPolicy>
    <rollingPolicy class="ch.qos.logback.core.rolling.SizeAndTimeBasedRollingPolicy">
        <fileNamePattern>${LOG_ROOT}/trustview-db-%d{yyyy-MM-dd}.%i.log.zip</fileNamePattern>
        <maxFileSize>250MB</maxFileSize>
        <maxHistory>60</maxHistory>
        <totalSizeCap>500MB</totalSizeCap>
    </rollingPolicy>
    <encoder>
        <pattern>%clr(%d{yyyy-MM-dd HH:mm:ss.SSS}){faint} %clr(%5p) %clr(---){faint} %clr([%15.15t]){faint} %clr(%-40.40logger{39}){cyan} %clr(:){faint} %m%n%wex</pattern>
    </encoder>
</appender>

Add the following loggers to the logback.xml file as well:

Additional logging appender that should be added to the logback.xml configuration file

<logger name="org.hibernate.SQL" level="DEBUG" additivity="false">
    <appender-ref ref="DB_PERFORMANCE"/>
</logger>
<logger name="org.hibernate.type.descriptor.sql.BasicBinder" level="TRACE" additivity="false">
    <appender-ref ref="DB_PERFORMANCE"/>
</logger>
<logger name="org.hibernate.engine.internal.StatisticalLoggingSessionEventListener" level="TRACE" additivity="false">
    <appender-ref ref="DB_PERFORMANCE"/>
</logger>
<logger name="org.hibernate.stat.internal.ConcurrentStatisticsImpl" level="TRACE" additivity="false">
    <appender-ref ref="DB_PERFORMANCE"/>
</logger>

Finally, register the appender in the same file:

<root level="INFO">
    <appender-ref ref="STDOUT" />
    <appender-ref ref="FILE" />
    <appender-ref ref="DB_PERFORMANCE"/>
</root>

Note

When using the logback.xml file, the Apache Tomcat Windows service does not need to be restarted. It is reloaded automatically shortly after the file is saved (Logback rescans it periodically, by default about once a minute). The logback.xml file only needs to be saved after the changes.

Step 2b (logback.groovy)

If you are using the groovy-based logback configuration (logback.groovy), locate the file and add the following. On the Embedded version of TrustView it is typically found here:

Example of how to add the appender in the logback.groovy configuration file (Embedded version)

C:\Program Files\TrustView-Embedded\tomcat\conf\logback.groovy

Tip

If you are still using the Standalone version of TrustView, it is instead found at C:\Program Files\Apache Software Foundation\Tomcat X.X_TrustView\conf\logback.groovy.

appender("DB_PERFORMANCE", FileAppender) {
    file = "${targetDir}/db-performance.log"
    append = true
    encoder(PatternLayoutEncoder) {
        pattern = "%d{HH:mm:ss.SSS} [%thread] %-5level %logger{36} - %msg%n"
    }
}

Then add the loggers:

logger("org.hibernate.SQL", DEBUG, ['STDOUT', 'DB_PERFORMANCE'], false)
logger("org.hibernate.type.descriptor.sql.BasicBinder", TRACE, ['STDOUT', 'DB_PERFORMANCE'], false)
logger("org.hibernate.engine.internal.StatisticalLoggingSessionEventListener", TRACE, ['STDOUT', 'DB_PERFORMANCE'], false)
logger("org.hibernate.stat.internal.ConcurrentStatisticsImpl", TRACE, ['STDOUT', 'DB_PERFORMANCE'], false)

Finally, register the DB_PERFORMANCE appender:

root(INFO, ['FILE', 'DB_PERFORMANCE'])

Important

When using the groovy-based logback configuration (logback.groovy), the Apache Tomcat Windows service must be restarted after the changes have been completed and saved.

2.6. Additional logging for troubleshooting

Click here for detailed steps

Beyond the database performance example above, any part of TrustView can be logged in more detail the same way, by adding extra <logger> entries (or logger(...) lines, for logback.groovy) to the same logback.xml/logback.groovy file - no extra installation is required.

Important

A freshly installed Embedded version only ships with the STDOUT and FILE appenders enabled by default. Everything below is something you add on top of that default, not something already active out of the box.

Add a <logger> entry for the relevant class or package name, at the suggested level, for example:

Example of raising the log level for a specific class in logback.xml

<logger name="certificate.management.tool.AgentConnectionController" level="INFO" additivity="false">
    <appender-ref ref="FILE"/>
</logger>

or, for logback.groovy:

logger("certificate.management.tool.AgentConnectionController", INFO, ['FILE'], false)

The following classes and packages are useful starting points for specific troubleshooting scenarios:

• Login/authentication issues (AD, SSO or local accounts) - org.springframework.security at TRACE, or more narrowly org.springframework.security.authentication.dao at TRACE for database/LDAP-backed logins specifically, and certificate.management.tool.LoginController at TRACE for the login flow itself.

• Database transaction issues (beyond slow queries, which the performance logging above already covers) - org.hibernate.engine.transaction.internal.TransactionImpl at TRACE.

• Monitored-object scanning in general (certificates, CRLs, domains and the other monitored object types all share this base class) - certificate.management.tool.AbstractMonitoredObjectService at TRACE.

• SSL endpoint scan or handshake failures - certificate.management.ssl.scanner.testscripts.SslHandshakeTestScript at INFO.

• AD-based SSL endpoint discovery failing (see also the related troubleshooting entry in Certificate Discovery) - certificate.management.ssl.scanner.ActiveDirectoryHostnameExtractionTestscriptService at INFO.

• Automation agent connection or activation problems - certificate.management.tool.AgentConnectionController at INFO, and certificate.management.tool.AgentConnectionActivationTemplateService at TRACE.

• ADCS connection or issuance problems - certificate.management.tool.api.AdcsConnectionController at TRACE.

• SCEP enrollment issues for automation agents - org.jscep at DEBUG.

• Scheduled scan or automation timing issues - org.quartz at TRACE.

• Broad, whole-application debugging (noisy - use only as a last resort) - certificate.management.tool at DEBUG.

Note

As with the database performance example above, a change to logback.xml is picked up automatically shortly after the file is saved (by default within about a minute), without restarting the Embedded TrustView service; a change to logback.groovy requires a restart.

Tip

The trustview-scanagent component (an external Scan agent, see Scan Agents) uses a different, simpler mechanism for its own logging - see Scan agent logging there.

2.7. Shipping logs to an external logging system

Click here for detailed steps

TrustView’s logs can be delivered to an external logging or monitoring system in a few different ways, depending on what that system is and how it is normally fed.

Tailing the log file (simplest)

The lowest-risk option, requiring no change to TrustView at all, is to point the external system’s own collection agent at the log file described under TrustView log file above and have it tail that file directly. This is how most log-management platforms are normally fed - for example Splunk’s Universal Forwarder, a Graylog Sidecar, or Filebeat for an Elastic/ELK stack - and it requires no restart and no change to logback.xml/logback.groovy.

Syslog

Logback (which TrustView uses) includes a syslog appender as standard, so no extra installation is required. Add it to logback.xml:

Example syslog appender in logback.xml

<appender name="SYSLOG" class="ch.qos.logback.classic.net.SyslogAppender">
    <syslogHost>syslog.example.com</syslogHost>
    <port>514</port>
    <facility>LOCAL0</facility>
    <suffixPattern>TrustView: %logger{36} - %msg</suffixPattern>
</appender>

<root level="INFO">
    <appender-ref ref="STDOUT" />
    <appender-ref ref="FILE" />
    <appender-ref ref="SYSLOG" />
</root>

or, for logback.groovy:

appender("SYSLOG", SyslogAppender) {
    syslogHost = "syslog.example.com"
    port = 514
    facility = "LOCAL0"
    suffixPattern = "TrustView: %logger{36} - %msg"
}
root(INFO, ['FILE', 'SYSLOG'])

Important

This built-in appender sends over plain UDP (RFC 3164) - it is not encrypted, and individual messages can be dropped under heavy load, which is normal for syslog. It is nonetheless the most broadly compatible option, since nearly every SIEM or log-management platform (Splunk, Graylog, a self-hosted ELK/Logstash stack via its syslog input, QRadar, etc.) accepts a syslog source.

E-mail alert on error

A related but different use case - getting notified immediately when something goes wrong, rather than aggregating every log line - can be done with Logback’s built-in SMTP appender, which also needs no extra installation:

Example e-mail alert appender in logback.xml

<appender name="EMAIL_ALERT" class="ch.qos.logback.classic.net.SMTPAppender">
    <smtpHost>smtp.company.com</smtpHost>
    <to>oncall@company.com</to>
    <from>trustview@company.com</from>
    <subject>TrustView error: %logger{20} - %msg</subject>
    <layout class="ch.qos.logback.classic.PatternLayout">
        <pattern>%d{yyyy-MM-dd HH:mm:ss} %-5level %logger{36} - %msg%n</pattern>
    </layout>
</appender>

<root level="INFO">
    <appender-ref ref="STDOUT" />
    <appender-ref ref="FILE" />
    <appender-ref ref="EMAIL_ALERT" />
</root>

Note

By default, the SMTP appender only sends a mail when an ERROR-level (or higher) event occurs - lower-level events are buffered as surrounding context inside that same mail, rather than each triggering a mail of their own.

Structured (JSON) shipping - Logstash/Graylog

For structured, field-based ingestion - for example feeding Logstash/ELK directly as JSON, or Graylog’s native GELF format - Logback needs an additional, third-party encoder library, which is not bundled with TrustView and has not been tested by Cryptomathic. Adding one works the same way as adding a JDBC driver: place the library’s .jar file (and any of its own dependencies) in C:\Program Files\TrustView-Embedded\tomcat\lib and it is picked up automatically on the next start.

Important

This option is shown for reference only - contact our Support before adding a third-party logging library to a production installation.

As an example, the commonly used logstash-logback-encoder library adds a Logstash-specific appender:

Example - requires the logstash-logback-encoder library (not bundled)

<appender name="LOGSTASH" class="net.logstash.logback.appender.LogstashTcpSocketAppender">
    <destination>logstash.example.com:5000</destination>
    <encoder class="net.logstash.logback.encoder.LogstashEncoder" />
</appender>

A Graylog-specific GELF appender (for example from a third-party GELF logging library) follows the same pattern, sending its own structured format instead of plain text.

Tip

The trustview-scanagent component (an external Scan agent, see Scan Agents) writes its own, separate log output and is not covered by the logback.xml/logback.groovy files described here - see Scan agent logging there.

2.8. Renewing your SSL/TLS certificate

Click here for detailed steps

Manual method

TrustView uses Apache Tomcat to host the application and therefore it is possible to assign an SSL certificate to the application. On the Embedded version of TrustView, the SSL certificate and the trustview.groovy configuration file are both located here:

Location of the config file and the SSL certificate (Embedded version)

C:\Program Files\TrustView-Embedded\Conf

In the file, you must locate the Connector element matching the port your TrustView is running on, typically 443 or 8443.

Example of Connector element

<Connector
port="443"
maxhttpheadersize="8192"
maxThreads="150"
minsparethreads="25"
maxsparethreads="75"
enablelookups="false"
disableuploadtimeout="true"
acceptcount="100"
scheme="https"
secure="true"
sslProtocol="TLS"
clientAuth="true"
SSLEnabled="true"
keystoreFile="conf/trustview_ssl.pfx"
keystorePass="CertificatePassword"
keystoreType="PKCS12"
/>

Tip

It is recommended to have a backup of the trustview.groovy file before modifying it.

Now update the following attributes of the Connector element to match the renewed certificate:

• keystoreFile

• keystorePass

If the new certificate is available in JKS format instead of PKCS12 format, make sure that keystoreType is set to JKS instead of PKCS12. If the new SSL certificate is in PFX format, the keystoreType still needs to be set to PKCS12.

Finally, restart the Embedded TrustView service for the change to take effect.

Important

If you are still using the Standalone version of TrustView, the process is the same, but there is no trustview.groovy file - the SSL certificate is instead specified in the Tomcat Apache server.xml configuration file, Tomcat-install-dir\conf\server.xml. First locate the Tomcat installation directory, typically:

Directory path of the Tomcat installation (Standalone version)

C:\Program Files\Apache Software Foundation\Tomcat X.X_TrustView

Update the same Connector element attributes there, then restart the Apache Tomcat service for the change to take effect.

Tip

If you are unable to locate the Apache Tomcat directory, contact our Support for assistance.

Automatic method

Go to Automation Tasks Add.

• Type an automation task name e.g. TrustViewSSL and specify a next run date to start the automation.

• Select the issuer you want for the certificate

• For the Key location select Key stored in TrustView.

• For the Add new deployment task select Deploy certificate to TrustView server

Once that has been filled out, press Create to set up the automation task, and the certificate for TrustView will now be automatically updated and deployed to the server.

Note

You only need one deployment task. Additional deployment tasks can be added after the first one, but you can simply press Create once Deploy certificate to TrustView server has been selected.

2.9. Update application specific Java version

Click here for detailed steps

Java requirements

TrustView Version	Java Version Recommended
TrustView v5.36.xx and below	Java 17.x
TrustView v5.38.xx and above	Java 23.x and above
TrustView v5.48.xx and above	Java 25.x and above

To update the Java version used by TrustView specifically, follow these steps:

Step 1

Download the new Java version from this link: Download OpenJDK.

Important

The version must be based on the relevant major Java version of the package type JDK. See the Java requirements in the table above for the specific version needed, depending on the version of TrustView you are currently running.

Choose the .msi version and run it to install it on the server, where TrustView is installed.

Step 2

On the Embedded version of TrustView, change the Windows Environment JAVA_HOME and Path variables to point at the newly installed Java version, then restart the Embedded TrustView service - the Embedded version automatically reads JAVA_HOME, so no further configuration file changes are needed.

Tip

If you want to verify that the changes have been applied, you can see the Java version used by TrustView, by logging into TrustView and going to Settings and then at the bottom of the page under Systeminfo.

Important

If you are still using the Standalone version of TrustView, go to the bin folder of the Apache Tomcat directory instead: C:\Program Files\Apache Software Foundation\Tomcat X.X_TrustView\bin, and open/run the application file called TrustVieww.exe.

Under the Java tab, the section named Java Virtual Machine must have the path changed to the path of the jvm.dll file of the newly installed Java version. The path can vary, but usually it can be found under the Java directory by following this path: ...\jre\bin\server\jvm.dll.

Once the new jvm.dll file has been selected, apply the changes and restart the Apache Tomcat Windows service, to get TrustView to use the newly installed Java version.

Step 3

Important

If you are only using a TrustView login with local users, this step is not required.

If you are using AD login for TrustView, you need to update your cacerts (the keystore) file to match the new Java version installed - see Configuration of AD integrated user management - Step 3 for its location on both the Embedded and Standalone versions.

2.10. Update Apache Tomcat

Click here for detailed steps

Important

This only applies to the Standalone version of TrustView. On the Embedded version, Tomcat is bundled with TrustView itself and is updated automatically whenever you upgrade to a new TrustView version - there is no separate Tomcat upgrade procedure to follow.

This is relevant if you are using the Standalone version of TrustView and want to move to a new major release of Apache Tomcat, but also if you need to move your TrustView instance to another server, or update Tomcat because of a potential vulnerability. In that case, a clean installation will then be necessary on the newly appointed server to host TrustView.

To update the Apache Tomcat application used to run TrustView, follow these steps:

Step 1

Important

It is highly recommended to create a backup of the old Apache Tomcat directory before proceeding, just in case. To back up the Java options for the Tomcat configuration, you need to go to C:\Program Files\Apache Software Foundation\Tomcat X.X_TrustView\bin and open trustvieww.exe and go to the Java tab. Under Java Options - copy the content to a text editor to back it up, since the trustvieww.exe can’t be opened again once the Tomcat service has been removed.

Download the new Apache Tomcat version from here. Choose major version 10, but minor versions may vary depending on releases - so simply choose the newest minor version available.

Download the .exe file by choosing the 32-bit/64-bit Windows Service Installer under the Binary Distributions segment of the download page.

Step 2

Once all the relevant files have been moved from the old Apache Tomcat directory to the new one, you can delete the old directory and the old Apache Tomcat Windows service, by using this command in a Command Prompt (with administrator rights):

sc delete <serviceName>

Tip

The name of a Windows service can always be found under Properties of the specific service.

Ensure that the service of the new TrustView instance has Startup type set to Automatic (Start Delayed). It is also recommended to set up a recovery method for the service, which can be done under Properties Recovery and by setting the First, Second and Third failure to Restart the Service. Then finish by setting Reset fail count after to 1 days and clicking apply before starting the service.

Step 3

Once the new Apache Tomcat version has been downloaded, install the new Apache Tomcat version and name the service (during the installation setup) TrustView. The old version, containing the current relevant files, is listed below:

• TrustView.groovy (located in the lib directory)

• context.xml (located in the conf directory)

• server.xml (located in the conf directory)

• logback.xml (located in the conf directory)

• .war file (located in the webapps directory)

Note

The webapps directory should always only contain a single .war file.

Optional files, depending on your setup (and if you have the files):

• cacerts (located in the conf directory and used for AD login)

• Any SSL certificates (located in the conf directory and used for the https connection)

These files need to be moved to the corresponding directories of the new Apache Tomcat installation directory, once that version has been installed.

Important

The Microsoft JDBC drivers used for the database connection also need to be moved or reinstalled, when a new version of Apache Tomcat is installed. See what files to move or how to install the Microsoft JDBC drivers here: Installing Microsoft JDBC drivers

Step 4

After the installation of the new Tomcat has been completed and the relevant files have been moved over, go to the bin directory and open the TrustVieww.exe file. Go to the Java tab in the dialogue box and at the bottom, set the HEAP memory:

• Initial memory pool - 512 MB

• Maximum memory pool - 3072 MB

Note

The HEAP memory pool is based on the available RAM on the server where TrustView is installed, so the maximum value can be increased if necessary.

In the Java Options, add this line if it is missing:

-Dlogging.config=C:\Program Files\Apache Software Foundation\Tomcat X.X_TrustView\conf\logback.xml

Important

Remember to adjust the file path if necessary.

2.11. Embedded version of Apache Tomcat

Click here for detailed steps

TrustView can be installed with 2 different versions of Tomcat, the Standalone and the Embedded version. The Embedded version is now the recommended and default version for new installations - it always includes an up-to-date version of Apache Tomcat with each new version of TrustView (if a new version of Tomcat is available), compared to the Standalone version, where you would have to update and maintain that task separately, each time it became relevant. The Standalone version remains supported for existing installations that have not yet migrated. Installing the embedded Tomcat version is only needed for completely new TrustView instances or if you need to move TrustView to a new server.

Important

It is highly recommended to create a backup of the TrustView server and database before proceeding, just in case you need to roll back.

To install TrustView with the embedded Apache Tomcat, follow these steps:

Step 1

Download the files if available or contact Support to get access to the embedded Apache Tomcat version of TrustView. A download link to the required files can be provided.

Step 2

Go to the TrustView-Embedded directory and move all the files to a new desired location of the server, e.g. C:\Program Files\TrustView-Embedded.

Tip

It does not have to be on the C: drive; it can be placed in other locations on the TrustView server. That folder will contain all the config files and log files related to TrustView.

Step 3

The following files must be added or moved (depending on whether you already have an existing TrustView installation), to the relevant folders of the TrustView-Embedded directory:

• Add the trustview-X_XX_XXX.war file to the root of the TrustView-Embedded directory

• Add/Move mssql-jdbc-X.X.X.jre8 to the tomcat\lib folder (You may consider downloading the newest version here)

• Add/Move logback.xml to the tomcat\conf folder (Only relevant if you have made any changes, since a version of the file already exists in the TrustView-Embedded directory)

• Move/Copy the relevant content of the trustview.groovy file to the tomcat\conf folder (Only relevant if you have an existing TrustView installation)

• Add/Move cacerts to the tomcat\conf folder (only relevant if you use AD-login or any of the integrations for TrustView)

• Add sslcertificate.pfx (The SSL certificate used for TrustView may be named differently) to the tomcat\conf folder

Important

The server.xml and context.xml files are not required with the embedded Tomcat version, since all the relevant settings within those files will exist solely in the trustview.groovy configuration file now.

Step 4

The next step is to open the trustview.properties file in the root of the TrustView-Embedded directory and configure the Java Options. A recommended setup looks like the following:

Example of the TrustView Java options

 javaopts=-Xms512m -Xmx3072m -Dcatalina.base=tomcat -Djavax.net.ssl.trustStore="C:\\Program Files\\TrustView-Embedded\\tomcat\\conf\\cacerts" -Djavax.net.ssl.trustStorePassword=changeit

Note

The path pointing towards the cacerts (keystore) file is not necessary if you do not want to use the AD-login method or any of the integrations (e.g. Azure and Citrix) with TrustView.

Important

In the same property file, confirm that the version (including the syntax) is correct and matches the version of the included .war file of the TrustView-Embedded directory. If the syntax or the version does not match the actual version of the .war file, TrustView will fail to start up correctly.

Step 5

To install the TrustView service, run the following PowerShell command:

How to install the embedded Tomcat service

 cd 'C:\Program Files\TrustView-Embedded\'
.\TrustView-Embedded-Service.exe install

Step 5b [Optional]

Consider updating your Java version used with TrustView, before starting the newly installed service for the embedded version - Compatible Java releases.

To choose a specific Java version to use with TrustView, change the Windows Environment and Path variables to match the desired Java version and restart the Embedded Tomcat service to apply the changes.

Important

The embedded version of TrustView automatically reads the JAVA_HOME variable.

Step 6

A new Windows service related to the embedded Tomcat should now have been installed with the name TrustView Embedded Service by default. Under Properties General, set the Startup type to Automatic (Delayed Start).

Important

Recovery should be set up on the installed Windows Service, in order to start the TrustView application up automatically, after a new installation or update. This can be done by going to Properties Recovery, on the service.

After all the (relevant) steps have been completed, start the embedded TrustView service, to start it up and access the URL in a browser.

2.12. Changing the SMTP gateway address

Click here for detailed steps

If the SMTP mail server changes, and you need to change the SMTP gateway address, follow these instructions:

Step 1

Locate the trustview.groovy file in the TrustView installation directory, typically:

Directory path of the Embedded TrustView configuration file

 C:\Program Files\TrustView-Embedded\tomcat\conf\trustview.groovy

Tip

If you are unable to locate the directory, contact our Support for assistance.

Step 2

Open the trustview.groovy file with a text editor (Notepad++ can be recommended) and locate the following lines at the end of the file:

Example of SMTP server setup in the TrustView configuration file

grails {
    mail {
        host = "smtp.company.com"
   }
}

Change the smtp.company.com part of the hostname to the new name of your SMTP gateway address and save the file, then restart the Embedded TrustView service for the change to take effect, and the SMTP gateway address will now be updated.

Important

If you are still using the Standalone version of TrustView, the configuration file is named TrustView.groovy and found here instead:

Typical directory path of the Standalone TrustView configuration file

C:\Program Files\Apache Software Foundation\Tomcat X.X_TrustView\lib\TrustView.groovy

After changing it, restart the Apache Tomcat service instead, for the change to take effect.

2.13. Using Office 365 SMTP server

Click here for detailed steps

This example shows how to configure an Office 365 SMTP server in the TrustView configuration file (trustview.groovy on the Embedded version, TrustView.groovy on the Standalone version - see Changing the SMTP gateway address above for the exact location on each):

Example of Office 365 SMTP setup

grails {
    mail {
     host = "Outlook.office365.com"
     port = 587
     username = "<insert username>"
     password = "<insert password>"
     props = ["mail.smtp.starttls.enable":"true" ,
              "mail.smtp.port":"587"
             ]
   }
}

Important

password above is stored in plain text in trustview.groovy/TrustView.groovy on disk. TrustView does not support Windows DPAPI, or any other file-level encryption, for this value, and gMSA - see How to use gMSA for the database above - is a Windows-integrated- authentication mechanism for the database connection specifically; it does not apply to SMTP AUTH. If the mail server supports OAuth2 (Office 365 does - see below), use SMTP OAuth2 settings in Global settings instead, which keeps the credential out of the file entirely.

2.14. Using OAuth2 with Office 365

Tip

Prefer entering these credentials under SMTP OAuth2 settings in Global settings instead of editing trustview.groovy/TrustView.groovy directly as shown below - the example below still writes the Client Secret into the file in plain text, the same way the basic-auth password above does. The UI path keeps the secret out of the file entirely, and TrustView stores it encrypted in its own database instead.

Click here for detailed steps

This example shows the setup using OAuth2 with Office 365 in the trustview.groovy/TrustView.groovy file:

Example of Office 365 SMTP with OAuth2

smtp {
    oauth2 {
        microsoftoffice365 {
            tenantid = "<insert tenant id>"
            clientid = "<insert client id>"
            clientsecret = "<insert client secret>"
        }
    }
}

grails {
    mail {
        host = "smtp.office365.com"
        port = 587
        username = "<insert e-mail sender, eg. example@domain.com>"
        password = ""
        props = ["mail.smtp.starttls.enable": "true",
                 "mail.smtp.auth.mechanisms": "XOAUTH2",
                 "mail.smtp.sasl.mechanisms": "XOAUTH2"
        ]
    }
}

Example of debugging the Office365 OAuth2 setup

smtp {
    oauth2 {
        microsoftoffice365 {
            tenantid = "<insert tenant id>"
            clientid = "<insert client id>"
            clientsecret = "<insert client secret>"
        }
    }
}

grails {
    mail {
        host = "smtp.office365.com"
        port = 587
        username = "<insert e-mail sender, eg. example@domain.com>"
        password = ""
        props = ["mail.smtp.starttls.enable": "true",
                 "mail.smtp.auth.mechanisms": "XOAUTH2",
                 "mail.debug.auth"          : "true",
                 "mail.debug"               : "true",
                 "mail.smtp.sasl.mechanisms": "XOAUTH2"
        ]
    }
}

Important

When using OAuth2, the support mail must match the sender mail you designated. So for example example@domain.com must match supportEmailAddress = "example@domain.com" line in the TrustView.groovy configuration file.

To get access to the required Microsoft Office365 details and set the required permissions, you will need to follow these steps:

Step 1 - Register a new application

Go to Microsoft Entra.

Navigate: Identity Applications App registrations

Click New registration.

On the Register an application page, fill in the following details:

Name: Enter a name for your application.

Supported account types (Choose one):

• Single Tenant

• Multitenant

Redirect URL: Change the dropdown to Public client/native (mobile & desktop) and set the value to:

Redirect URL

 urn:ietf:wg:oauth:2.0:oob

Click Register.

Save Application Details. On the next page, copy the Application (client) ID and the Directory (tenant) ID. Save these for later use in the TrustView.groovy configuration file. You can access this information anytime via: Identity Applications App registrations All Applications.

Step 2 - Assign API permissions

Go to API permissions Add a permission.

Go to the APIs my organization uses tab. Search for and select Office 365 Exchange Online. (This option will only appear if the account has an active Office 365 subscription with Exchange).

Search for Application permissions SMTP.SendAsApp.

Click Add permissions.

Grant admin consent by selecting Grant admin consent for <Your organization> and confirming the consent dialog.

Step 3 - Generate client secret

Go to Certificates & Secrets New client secret.

Enter description, choose expiration, and click Add. Then immediately copy and securely store the Client Secret.

Important

Copy the value of the client secret and save it. Once you close the screen, you won’t be able to access it again. If lost, you will need to create a new client secret.

Step 4 - Register the Service Principal with Exchange Online

The above steps enable the application to use the Exchange Online API. To grant access to specific mailboxes:

Use Microsoft 365 Cloud Shell or Exchange Online PowerShell:

Connect to Exchange

 Connect-ExchangeOnline

Retrieve the Application and Object ID

Go to Azure Enterprise applications and locate your application. Copy the Application ID. Copy the Object ID.

Create the Service Principal (if required)

The Application ID should sync automatically to Exchange Online as a Service Principal. However, in some cases, delays or issues with synchronization may prevent it from being recognized. If the Add-MailboxPermission commands below fail with an error like “Couldn’t find a service principal with the following identity”, create the service principal using this command:

Command to create new service principal

 New-ServicePrincipal -AppId {{Application-ID}} -ObjectId {{Object-ID}}

Replace {{Application-ID}} with the Application ID and {{Object-ID}} with the Object ID. This step ensures the Service Principal is properly registered with Exchange Online.

Step 5: Assign Mailbox Permissions (Critical Step)

Single sender:

Assign permission to system mailbox:

Command to assign permission to the system mailbox

 Add-MailboxPermission -Identity "mail_address_to_send_from@domain.com" -User "<App Object-ID>" -AccessRights FullAccess

Multiple user senders:

Assign permission to each mailbox individually:

Command to assign permissions to individual mailboxes

$mailboxes = @("user1@domain.com", "user2@domain.com") # Add users
foreach ($mbx in $mailboxes) {
  Add-MailboxPermission -Identity $mbx
    -User "<App Object-ID>" -AccessRights FullAccess
}

Enable SMTP AUTH for Mailboxes

SMTP AUTH must be enabled on each mailbox that you intend to send mail from, using OAuth 2.0 with Exchange Online. This step is required even if you have granted mailbox permissions to the app registration.

Microsoft 365 Admin Center Steps

• Go to Microsoft 365 Admin Center

• Navigate to Users Active users

• Click the user whose mailbox will send emails

• In the user flyout, select the Mail tab

• Under Email apps, click Manage email apps

• Ensure the checkbox for Authenticated SMTP is checked

Important

If Authenticated SMTP is disabled, email delivery via SMTP will silently fail.

2.15. How to change the notification sender (support mail)

Click here for detailed steps

The support mail is used as the sender of most notification e-mails sent from TrustView. Certificate checkout mail is the one exception - its own sender can be overridden separately via the Mail sender address field under Message Templates (Certificate checkout emails). SMS notifications don’t use an email sender at all.

Tip

It is recommended to change the support mail address in TrustView, to match the e-mail domain of your organization.

Step 1

Locate the trustview.groovy file in the TrustView installation directory, typically:

Directory path of the Embedded TrustView configuration file

 C:\Program Files\TrustView-Embedded\tomcat\conf\trustview.groovy

Tip

If you are unable to locate the directory, contact our Support for assistance.

Step 2

Open the trustview.groovy file with a text editor (Notepad++ can be recommended) and add or locate the following line in the file:

The supportEmailAddress line sets the sender for TrustView’s notification e-mails

 supportEmailAddress = "company@domain.com"

Change the company@domain.com example value to something else that fits your organization, such as no-reply@domain.com. A fresh installation’s configuration file may not include this line at all yet - if it’s missing, TrustView falls back to a built-in default sender address until you add it. This can be a shared mailbox or a no-reply mailbox, in case you want to discourage users from replying to e-mails sent from TrustView.

Important

If you are still using the Standalone version of TrustView, the configuration file is named TrustView.groovy and found here instead:

Typical directory path of the Standalone TrustView configuration file

C:\Program Files\Apache Software Foundation\Tomcat X.X_TrustView\lib\TrustView.groovy

2.16. Releasing the Change log lock

Click here for detailed steps

When TrustView makes a database update, Liquibase reads from the DATABASECHANGELOG table in the database to determine which changesets need to run. Liquibase uses a lock to avoid conflicts between concurrent updates, which can happen if multiple changes happen at the same time for the same database instance. If TrustView makes another update during this time, Liquibase waits until the lock releases before running it.

This example shows how the database change log lock should be displayed in a trustview-logback-xxxx-xx-xx.log file if it was acquired successfully:

20XX-XX-XX 00:00:00.000  INFO --- [ost-startStop-1] liquibase                                : Successfully acquired change log lock
20XX-XX-XX 00:00:00.000  INFO --- [ost-startStop-1] liquibase                                : Reading from [dbo].[DATABASECHANGELOG]
20XX-XX-XX 00:00:00.000  INFO --- [ost-startStop-1] liquibase                                : Successfully released change log lock

Important

If the change log lock is not successfully acquired, TrustView will not be able to run and will not start up until the lock is released.

This example shows how the database change log lock error would be displayed in a trustview-logback-xxxx-xx-xx.log file:

20XX-XX-XX 00:00:00.000  INFO --- [ost-startStop-1] liquibase                                : Waiting for changelog lock....
20XX-XX-XX 00:00:00.000  INFO --- [ost-startStop-1] liquibase                                : Waiting for changelog lock....
liquibase.exception.LockException: Could not acquire change log lock.  Currently locked by servername (127.0.0.1) since XX/XX/XX 0:00 PM
     at liquibase.lockservice.StandardLockService.waitForLock(StandardLockService.java:190)
     at liquibase.Liquibase.update(Liquibase.java:196)
     at liquibase.Liquibase.update(Liquibase.java:192)
     at liquibase.integration.spring.SpringLiquibase.performUpdate(SpringLiquibase.java:431)
     at org.grails.plugins.databasemigration.liquibase.GrailsLiquibase.performUpdate(GrailsLiquibase.groovy:83)
     at liquibase.integration.spring.SpringLiquibase.afterPropertiesSet(SpringLiquibase.java:388)

Clear the lock in the database

There are several ways of clearing or unlocking the change log lock in the TrustView database:

Method 1

Drop or delete the DATABASECHANGELOGLOCK table in the TrustView database; it will then be recreated, and the lock will be released after you restart the TrustView Tomcat service.

Method 2

Run the following command in the database:

Example of SQL command

UPDATE DATABASECHANGELOGLOCK SET LOCKED=0, LOCKGRANTED=null, LOCKEDBY=null where ID=1;

Note

You may need to replace LOCKED=0 with LOCKED=FALSE.

2.17. TrustView log file

Click here for detailed steps

Locate the TrustView log file

There may be cases where you need the trustview-xxxx-xx-xx.log file for troubleshooting or we need it to provide support if we do not have direct access to the server for your TrustView installation.

The log file can typically be found in this location, depending on the TrustView directory name:

Typical location of the log files for the Embedded version of TrustView

 C:\Program Files\TrustView-Embedded\tomcat\logs

The log file can be opened with any text editor but Notepad++ can be recommended.

If you are still using the Standalone version of TrustView, the log files are located elsewhere:

Typical location of the log files for the Standalone version of TrustView

 C:\Program Files\Apache Software Foundation\Tomcat X.X_TrustView\logs\trustview-date

Send the TrustView log file

It is also possible to send specific log files directly from TrustView to our backend, instead of locating the log files manually.

Go to the Support section, found in the top right corner of TrustView.

Under Send log files to Technical support, you can select all the available log files that are relevant for the situation and then press Send to Technical support to send the selected log files securely to Cryptomathic, for analysis.

Note

It requires a user of the role Superuser or Global Administrator to be able to access this and send the log files.

2.18. System status

The Systemstatus menu item gives an overview of TrustView’s own health, useful when troubleshooting:

• Subcomponents - whether the local scanner, the certificate ordering backend and the SMS gateway are currently Available or Unavailable, plus a history of their availability over time.

• Active scans - scans currently running, with their name, type, start time, running duration and scan agent, along with the total number of running and queued scan jobs.

• The current TrustView version and memory usage.

2.19. Limit how many scan jobs run concurrently

Click here for detailed steps

TrustView’s scheduler checks for scans that are due roughly every 30 seconds, and each time it runs it caps how many new scan jobs it starts, so a large backlog can’t overwhelm the scan agent(s) all at once. Two properties control that cap:

• maxJobsToStart - the total number of scan jobs allowed to start per check. Defaults to 5.

• maxTimeConsumingJobsToStart - a share of that same cap reserved specifically for network port scans (see Certificate Discovery), so a long queue of network scans can’t starve every other scan type out of its turn. Defaults to 2 if the property isn’t set at all.

• scantaskProcessingBatchSize - how many finished scan results get processed per database transaction. Defaults to 10. This is a separate throughput knob from the two above - raise it if you have a large number of scans finishing at once and want them processed through the database in bigger batches.

Step 1

Locate the trustview.groovy file in the TrustView installation directory, typically:

Directory path of the Embedded TrustView configuration file

 C:\Program Files\TrustView-Embedded\tomcat\conf\trustview.groovy

Important

If you are still using the Standalone version of TrustView, the configuration file is named TrustView.groovy and found here instead:

Typical directory path of the Standalone TrustView configuration file

C:\Program Files\Apache Software Foundation\Tomcat X.X_TrustView\lib\TrustView.groovy

Step 2

Open the file with a text editor and add (or adjust) the properties:

Example scan-job throttling properties

maxJobsToStart = "25"
maxTimeConsumingJobsToStart = 4
scantaskProcessingBatchSize = 20

Tip

Raise maxJobsToStart if your scan agent(s) have spare capacity and you want more scans running per check. Raise maxTimeConsumingJobsToStart specifically if network scans are being crowded out by other scan types, or lower it if network scans are themselves crowding out everything else. Raise scantaskProcessingBatchSize if the database itself is the bottleneck once more scans are allowed to run.

Save the file and restart the Embedded TrustView service for the change to take effect (or the Apache Tomcat service, if you are using the Standalone version).

2.20. Change how often discovery and monitoring scans run

Click here for detailed steps

Several of the periodic scans described in Certificate Discovery and Azure Integration run on a fixed daily interval out of the box. Each one has its own property, so they can be tuned independently:

• nmapscanIntervalDays - interval for network scans (in days). Defaults to 7.

• adscanIntervalDays - interval for AD SSL endpoint discovery (in days). Defaults to 7.

• domainscanIntervalDays - interval for domain scanning (in days). Defaults to 7.

• azureIntegrationIntervalDays - interval for the Azure Key Vault integration scan (in days). Defaults to 1.

• monitoringinterval - how often (in seconds) TrustView checks monitored certificates for upcoming expiry. Defaults to 300 (5 minutes).

There is also one property that doesn’t change how often scans run, but when in the day they start:

• scanScheduleJobDailyOffset - shifts the time of day the daily scans above fire, as a number of seconds added to the scheduler’s own reference point. Defaults to 0. Use this to spread scanning load across the day, or to move it outside business hours.

Step 1

Locate the trustview.groovy file in the TrustView installation directory, typically:

Directory path of the Embedded TrustView configuration file

 C:\Program Files\TrustView-Embedded\tomcat\conf\trustview.groovy

Important

If you are still using the Standalone version of TrustView, the configuration file is named TrustView.groovy and found here instead:

Typical directory path of the Standalone TrustView configuration file

C:\Program Files\Apache Software Foundation\Tomcat X.X_TrustView\lib\TrustView.groovy

Step 2

Open the file with a text editor and add (or adjust) the properties that are relevant to you:

Example scan-interval properties

nmapscanIntervalDays = 14
domainscanIntervalDays = 14
scanScheduleJobDailyOffset = 7200

Tip

Only add the properties you actually want to change - any property left out keeps its default.

Save the file and restart the Embedded TrustView service for the change to take effect (or the Apache Tomcat service, if you are using the Standalone version).

2.21. Disable TLS certificate validation for TrustView’s own connections

Click here for detailed steps

Important

This turns off certificate validation for every outbound HTTPS/TLS connection TrustView itself makes (ADCS, DNS providers, the Cryptomathic backend, and so on) - not just one of them. Only use it as a temporary diagnostic step, or in a closed environment where you fully control every endpoint TrustView connects to. Prefer adding the missing CA to the trust store instead, wherever that’s possible.

The ssltrustcheckingenabled property controls this globally, and defaults to true (validation enabled). Setting it to false turns off SSL trust checking for the entire TrustView instance from the next restart onwards.

Step 1

Locate the trustview.groovy file in the TrustView installation directory, typically:

Directory path of the Embedded TrustView configuration file

 C:\Program Files\TrustView-Embedded\tomcat\conf\trustview.groovy

Important

If you are still using the Standalone version of TrustView, the configuration file is named TrustView.groovy and found here instead:

Typical directory path of the Standalone TrustView configuration file

C:\Program Files\Apache Software Foundation\Tomcat X.X_TrustView\lib\TrustView.groovy

Step 2

Open the file with a text editor and add:

Disable SSL trust checking

ssltrustcheckingenabled = false

Save the file and restart the Embedded TrustView service for the change to take effect (or the Apache Tomcat service, if you are using the Standalone version). Remove the line again (or set it back to true) once the underlying trust issue has been fixed.

2.22. Remove SSL endpoints via configuration

Click here for detailed steps

SSL endpoints are normally removed from the SSL endpoints list in the UI, but a list of endpoint IDs can also be queued for removal through configuration, which is useful for removing a large, known set of endpoints in one go without clicking through each of them.

Step 1

Locate the trustview.groovy file in the TrustView installation directory, typically:

Directory path of the Embedded TrustView configuration file

 C:\Program Files\TrustView-Embedded\tomcat\conf\trustview.groovy

Important

If you are still using the Standalone version of TrustView, the configuration file is named TrustView.groovy and found here instead:

Typical directory path of the Standalone TrustView configuration file

C:\Program Files\Apache Software Foundation\Tomcat X.X_TrustView\lib\TrustView.groovy

Step 2

Open the file with a text editor and add the IDs of the SSL endpoints to remove:

Queue SSL endpoints for removal

sslEndpointsToRemoveById = [101, 102, 103]

Tip

The ID of an SSL endpoint is visible in the browser’s address bar when viewing its detail page.

Important

This only runs once, during TrustView’s startup. Restart the Embedded TrustView service (or the Apache Tomcat service, on the Standalone version) to trigger the removal, then remove the line again afterwards - it isn’t needed once the endpoints have been deleted, and leaving stale IDs in place has no effect on endpoints that no longer exist.

2.23. Expose a Prometheus metrics endpoint

Click here for detailed steps

TrustView can expose a Prometheus-compatible metrics endpoint, for organizations that already scrape Prometheus metrics from their infrastructure.

Step 1

Locate the trustview.groovy file in the TrustView installation directory, typically:

Directory path of the Embedded TrustView configuration file

 C:\Program Files\TrustView-Embedded\tomcat\conf\trustview.groovy

Important

If you are still using the Standalone version of TrustView, the configuration file is named TrustView.groovy and found here instead:

Typical directory path of the Standalone TrustView configuration file

C:\Program Files\Apache Software Foundation\Tomcat X.X_TrustView\lib\TrustView.groovy

Step 2

Open the file with a text editor and add:

Enable the Prometheus metrics endpoint

prometheusHttpServerEnabled = true
prometheusHttpServerPort = 14504

Tip

prometheusHttpServerPort defaults to 14504 if left out - only add it if that port is already in use.

Save the file and restart the Embedded TrustView service for the change to take effect (or the Apache Tomcat service, if you are using the Standalone version).

2.24. Allow cross-origin API requests (CORS)

Click here for detailed steps

By default, a browser-based script running on another site can’t call TrustView’s API directly, because TrustView doesn’t send the Access-Control-Allow-Origin header browsers require for that. If you’re building a web application on another domain that needs to call the TrustView API directly from the browser, add that domain to corsEnabledOrigin.

Step 1

Locate the trustview.groovy file in the TrustView installation directory, typically:

Directory path of the Embedded TrustView configuration file

 C:\Program Files\TrustView-Embedded\tomcat\conf\trustview.groovy

Important

If you are still using the Standalone version of TrustView, the configuration file is named TrustView.groovy and found here instead:

Typical directory path of the Standalone TrustView configuration file

C:\Program Files\Apache Software Foundation\Tomcat X.X_TrustView\lib\TrustView.groovy

Step 2

Open the file with a text editor and add the origin(s) that should be allowed to call the API:

Allow one or more origins to call the TrustView API

corsEnabledOrigin = ["https://my-internal-app.example.com"]

Tip

This takes a list, so more than one origin can be added, separated by commas inside the [ ] brackets.

Save the file and restart the Embedded TrustView service for the change to take effect (or the Apache Tomcat service, if you are using the Standalone version).

2.25. Get an e-mail notification on every login

Click here for detailed steps

For environments that want an audit trail of every sign-in to TrustView, loginNoticeRecipient sends a short e-mail to a chosen address each time any user logs in. This is unset (no notice sent) by default.

Step 1

Locate the trustview.groovy file in the TrustView installation directory, typically:

Directory path of the Embedded TrustView configuration file

 C:\Program Files\TrustView-Embedded\tomcat\conf\trustview.groovy

Important

If you are still using the Standalone version of TrustView, the configuration file is named TrustView.groovy and found here instead:

Typical directory path of the Standalone TrustView configuration file

C:\Program Files\Apache Software Foundation\Tomcat X.X_TrustView\lib\TrustView.groovy

Step 2

Open the file with a text editor and add:

Send a notice on every login

loginNoticeRecipient = "security-team@example.com"

Save the file and restart the Embedded TrustView service for the change to take effect (or the Apache Tomcat service, if you are using the Standalone version).

2.26. Escape invalid characters in .xml and .groovy files

Click here for detailed steps

Escape invalid characters in .xml and .groovy files

If any of the passwords included in the xml and groovy files contain one or more of the characters in the table below, the Apache Tomcat service will not start and the character(s) must be escaped or the password changed, so it does not contain any of the invalid characters.

Character	Escape String
&	&
'	'
"	"
<	&lt;
>	&gt;

2.27. Use certificate and key from Microsoft certstore in Apache Tomcat

Click here for detailed steps

We recommend using Windows Server 2016 or later.

The following is specified in the Tomcat Apache server.xml configuration file, located in Tomcat-install-dir\conf\server.xml.

Update and/or add the following in the server.xml to match your configuration:

• keyAlias=”friendly name of the cert”

• keystoreType=”Windows-root or Windows-MY”

• keystoreFile=” “

• keystorePass=” “

KeyAlias can be found in mmc - certificate - properties - friendly name.

Note

There are multiple keystoreType values for the Windows connector configuration: Windows-MY and Windows-Root, depending on where the certificate is located.

Windows-MY - System Accounts Personal certificate store

Windows-Root - Trusted Root CA store

Because Tomcat is running as a service, you will need to use Windows-Root and place the certificate in the Trusted Root CA store or set the certificate into System accounts Personal certificate store and use Windows-MY. It won’t work with my user account or computer account for this.

Tip

Ensure your certificates are in the correct store by running certmgr.msc.

Server.xml example

<Connector port="443" protocol="org.apache.coyote.http11.Http11NioProtocol"
           maxThreads="200"
           scheme="https"
           secure="true"
           SSLEnabled="true"
           keyAlias="**Test**"
           keystoreType="**Windows-root**"
           keystoreFile=""
           keystorePass=""
           clientAuth="false"
           sslProtocol="TLS"
           sslEnabledProtocols="TLSv1.2,TLSv1.3"

Important

This describes the server.xml-based setup used on the Standalone version of TrustView. The Embedded version likely supports the same Windows certificate store via the equivalent Spring Boot properties in trustview.groovy (server.ssl.key-alias, server.ssl.key-store-type, etc., following the same server.* convention used elsewhere in this guide for the Embedded version), but this has not been verified against a running Embedded instance - confirm with our Support before relying on it.

2.28. Configure Heap memory

Click here for detailed steps

To configure the Heap memory for the Embedded version of TrustView, adjust the properties:

Locate the Embedded TrustView property file

C:\Program Files\TrustView-Embedded\trustview.properties

Important

The path of the property file may be different, depending on where you have the TrustView-Embedded directory located. It may be on another drive.

Adjust the Java options in the property file

javaopts=-Xms512m -Xmx3072m

Tip

The first value (-Xms512m) is the minimum memory allowed and the last value (-Xmx3072m) is the maximum amount of Heap memory allowed to be allocated to TrustView. Adjust it depending on the GB of RAM available on the TrustView server.

Important

If you are still using the Standalone version of TrustView, configure the Heap memory for the TrustView instance via the application configuration instead:

Locate and open the trustvieww.exe file (Standalone version)

C:\Program Files\Apache Software Foundation\Tomcat X.X_TrustView\bin

Go to the Java tab and adjust the Heap memory section at the bottom to meet your needs, using the same minimum/maximum recommendations as above.

2.29. Enable HTTP compression

Click here for detailed steps

Enabling HTTP compression can have the effect of improving performance. To enable HTTP compression on the Embedded version of TrustView, add the following line to the Embedded Tomcat section of the trustview.groovy configuration file:

Enable HTTP compression for the Embedded version

server.compression.enabled=true

Important

If you are still using the Standalone version of TrustView, enable it in the server.xml file instead. First locate it:

Locate the server.xml file (Standalone version)

C:\Program Files\Apache Software Foundation\Tomcat X.X_TrustView\conf

Open the server.xml file and add the following line in 2 locations of the file:

Enable HTTP compression

compression="on"

Example of where to add the HTTP compression

<Connector port="443" protocol="org.apache.coyote.http11.Http11NioProtocol"
               maxThreads="200"
               scheme="https"
               secure="true"
               compression="on"
    <UpgradeProtocol className="org.apache.coyote.http2.Http2Protocol" compression="on"/>
</Connector>

2.30. Customize TrustView instance

Click here for detailed steps

If you have more than one TrustView instance, it may feel necessary to be able to distinguish them easily in the browser. You can do so by adding one or more of these options in the TrustView configuration file (trustview.groovy on the Embedded version, TrustView.groovy on the Standalone version - see Changing the SMTP gateway address above for the exact location on each):

TrustView instance configuration options

trustview.instance.titleSuffix = "- Tab Instance Text"
trustview.instance.faviconMode = "default"
trustview.instance.faviconLabel = "1"
defaultLocale = new Locale("en", "US")

Note

trustview.instance.faviconMode has the options of "light" or "default", which means the browser favicon icon changes to either a light or default version of the TrustView favicon. The light version works best on dark browsers, to contrast it.

The trustview.instance.titleSuffix option allows you to add an additional text element to the browser tab, so in the example above the tab would be called TrustView - Tab Instance Text.

trustview.instance.faviconLabel allows you to add a label to the browser favicon icon. This option can be combined with the trustview.instance.faviconMode so the label can be used on both options available for the mode. This can be used to number the TrustView instances if necessary, but is not limited to numbers only. It is also possible to add text or just single characters.

defaultLocale sets the UI language shown to a user the first time they log in (a user can still change their own language afterwards under their personal settings). TrustView ships with Danish as the default (new Locale("da", "DK")); the example above switches the instance-wide default to English instead.

Once one or more of the options have been added to the trustview.groovy configuration file, save the file and restart the Tomcat service (or reload the configuration file from TrustView), to make the changes take effect. You may need to refresh the browser, since the previous browser changes may be cached.

2.31. Use proxy to change the TrustView URL

Click here for detailed steps

By default the URL for TrustView will be servername.domainname, but to change the URL without having to use DNS forwarding, IIS Routing or other solutions, you can use a proxy.

On the Embedded version of TrustView, this takes place in the trustview.groovy configuration file, and the line to add is the following:

server.proxyName="trustview.domainname.com"

Note

The line can in theory be added anywhere in the configuration file, but it is recommended to add it to the Embedded tomcat section, which can usually be found at the bottom of the configuration file.

Restart the Embedded TrustView service, to make the changes take effect.

Important

If you are still using the Standalone version of TrustView, implement these changes into the SSL connector of the server.xml file instead:

• proxyName=”trustview.domainname.com”

• proxyPort=”443”

Example of SSL connector with proxy setup (Standalone version)

<Connector address="127.0.0.1" port="8080" maxHttpHeaderSize="65536" protocol="HTTP/1.1"
   connectionTimeout="20000"
   redirectPort="8443" />

<Connector port="443" protocol="org.apache.coyote.http11.Http11NioProtocol"
        maxThreads="200"
        scheme="https"
        secure="true"
        SSLEnabled="true"
        proxyName="trustview.domainname.com"
        proxyPort="443"
        keystoreFile="conf\trustview-ssl.pfx"
        keystoreType="PKCS12"
        keystorePass="********"
        clientAuth="false"
        sslProtocol="TLS"
        sslEnabledProtocols="TLSv1.2+TLSv1.3"

ciphers="TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384,
               TLS_ECDH_RSA_WITH_AES_256_GCM_SHA384,TLS_ECDH_ECDSA_WITH_AES_256_GCM_SHA384,
               TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256,
               TLS_ECDH_RSA_WITH_AES_128_GCM_SHA256,TLS_ECDH_ECDSA_WITH_AES_128_GCM_SHA256,
               TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384,TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384,
               TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA,TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA,
               TLS_ECDH_RSA_WITH_AES_256_CBC_SHA384,TLS_ECDH_ECDSA_WITH_AES_256_CBC_SHA384,
               TLS_ECDH_RSA_WITH_AES_256_CBC_SHA,TLS_ECDH_ECDSA_WITH_AES_256_CBC_SHA,
               TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256,TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256,
               TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA,TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA,
               TLS_ECDH_RSA_WITH_AES_128_CBC_SHA256,TLS_ECDH_ECDSA_WITH_AES_128_CBC_SHA256,
               TLS_ECDH_RSA_WITH_AES_128_CBC_SHA,TLS_ECDH_ECDSA_WITH_AES_128_CBC_SHA">

            <UpgradeProtocol className="org.apache.coyote.http2.Http2Protocol" />
</Connector>

After the changes, save the file and change the contextPrefix property in the TrustView.groovy file, to match the one set as proxyName in the server.xml file:

contextPrefix="trustview.domainname.com"

Once that has been done, restart the Apache Tomcat service, to make the changes take effect.

2.32. Configure an outbound proxy

Click here for detailed steps

Note

This is different from Use proxy to change the TrustView URL above, which is about placing TrustView behind a reverse proxy. This section is about routing TrustView’s own outbound connections - to certificate authorities (e.g. Let’s Encrypt), DNS provider APIs used for domain validation, Certificate Transparency log lookups, and the Cryptomathic backend used by features such as Domain scanning - through an HTTP(S) proxy.

Important

This method only applies to the Embedded version of TrustView.

If the TrustView server’s outbound internet access requires going through a proxy, add the proxy configuration to the javaopts line of the trustview.properties file:

Locate the Embedded TrustView property file

C:\Program Files\TrustView-Embedded\trustview.properties

Add the proxy Java options to the property file

javaopts=-Xms512m -Xmx3072m -Dhttp.proxyHost=proxy.domain.com -Dhttp.proxyPort=8080 -Dhttps.proxyHost=proxy.domain.com -Dhttps.proxyPort=8080

Tip

If the proxy requires authentication, add the following to the same line as well:

-Dhttps.proxyUser=<username> -Dhttps.proxyPassword=<password>

Important

Restart the Embedded TrustView service after changing trustview.properties, for the new Java options to take effect.