1.4.1. Dashboard Installation

1.4.1.1. Requirements

The dashboard server is implemented in Java and requires high disk access performance and a reliable network connection to its clients.

Processor

Depending on the host OS, one of the following processor architectures is required:

  • Windows: x86-64

  • GNU/Linux: x86-64 or ARM64

  • macOS: ARM64

We recommend two or more cores, depending on the number of simultaneous clients.

Memory

We recommend at least 1 GB of free system memory.

Hard disk

Storage requirements depend heavily on the size of your projects and the frequency of your analysis runs. As a rule of thumb, allow 1 GB per project. Analysis data should be stored on a disk local to the dashboard server.

The dashboard server should run fine on the following operating systems:

Windows

Windows 10 (version 1809 or newer) or Windows Server 2019 or newer (64-bit).

For the dashboard Windows service wrapper, .NET Framework 4.6.1 or higher is required.

GNU/Linux

with a 64-bit kernel 3.17 or newer and GLIBC version 2.28 or newer.

macOS

Version 14 or newer (64-bit).

Additional software requirements:

Python

The Axivion Suite comes with its own Python interpreter, but using a different one is also supported. We support 64-bit versions 3.12, 3.13, 3.14, or 3.15, available at https://www.python.org/

Java Runtime Environment

We support the latest updates for versions 17, 21, and 25 of the 64-bit HotSpot Java Runtime Environment.

Other 64-bit Java 17 (or newer) runtimes should also work.

On Windows, the Java security provider “SunMSCAPI” (jdk.crypto.mscapi) is required. By default, this provider is included in the JRE and JDK. If a stripped-down Java installation without SunMSCAPI is used, a fallback random number generator algorithm can be enabled by setting the environment variable AXIVION_ALLOW_DEFAULT_SECURE_RANDOM=YES (case-sensitive).

1.4.1.2. Understanding the Dashboard

First, let’s examine the components relevant to understanding and setting up the dashboard.

The Axivion Dashboard Server is a Java application that runs as a background process. It primarily acts as an HTTP server to serve browser clients, but it also exposes an HTTP JSON API for other purposes.

To enable the dashboard to send emails via its Erosion Notification System, described in Section Erosion Notification System, you must also provide access to a mail server.

The displayed erosion data is stored in SQLite database files. Each project has one database file shared between the dashboard and your analysis setup; this file must have the .db suffix. The dashboard is used to display the erosion data within these databases, while your analysis setup (possibly implemented as continuous integration) fills and updates the files. An additional database file per project, maintained exclusively by the dashboard, stores issue annotations made by users. This file is only valid when used with its corresponding analysis database file and is therefore stored alongside it on the file system. It shares the same name but uses the .dbx suffix.

For details on the continuous integration process, please refer to the Continuous Integration Guide.

A diagram illustrating this general concept is shown in Figure Context of the dashboard..

Context of the dashboard.

Context of the dashboard.

By default, dashboard users are authenticated via an integrated mechanism that stores hashed passwords in the internal dashboard configuration. Additionally, the dashboard can authenticate users via LDAP, Active Directory (Windows only), OpenID Connect (OIDC) single sign-on, or an authenticating HTTP proxy. It can also grant access without credentials using a designated default user; see Section Authentication.

Caution

Dashboard administrators theoretically have the means to execute arbitrary processes on the host machine using the permissions of the account running the dashboard server.

1.4.1.3. Server Control Script

To control the Axivion Dashboard Server, a service script dashserver is provided within the Axivion Suite command line.

Basic usage:

dashserver <subcommand> <options..>

List the available subcommands:

dashserver --help

List the available options of a specific subcommand:

dashserver <sub-command> --help

Key subcommands and their most frequently used options are listed below. Consult the script itself for the full list.

Subcommand

Meaning

init

Create a configuration from a specified template.

start

Starts the Axivion Dashboard Server.

stop

Stops the Axivion Dashboard Server.

install

Installs the Axivion Dashboard Server as a system service (not supported on macOS).

uninstall

Uninstalls the Axivion Dashboard Server system service (not supported on macOS).

status

Displays whether the Axivion Dashboard Server is currently running.

restore-admin

Enables the user specified with --user (default admin), sets a new random password, and grants the Log in and Administrate permissions; creates the user if they do not exist.

install-project

Registers the analysis database specified with --dbfile as a project with database mode shared_database.

uninstall-project

Removes the project with database mode shared_database specified with --name from the Axivion Dashboard Server configuration; the database files are preserved.

delete-project

Deletes the project with database mode managed_upload specified with --name along with its files.

certificate

Creates a keystore from certificates and private keys and configures the Axivion Dashboard Server to use it; see Using the Certificate Wizard to Create a Key Store and Install it.

Options of the start subcommand in addition to --confdir:

Option

Meaning

--local

Uses the current user’s local Axivion Dashboard Server; see Local Build. --confdir is ignored.

--port

The TCP port the Axivion Dashboard Server listens on. Overrides HttpPort and HttpsPort in dashboard2.config.

--restart

Stops a running Axivion Dashboard Server before starting it. When using --local, the local configuration is deleted in between.

--nodetach

Keeps the Axivion Dashboard Server process attached to the console instead of running it in the background.

--install_file

Registers the specified analysis database as a project, even if the Axivion Dashboard Server is already running.

--noauth

Disables authentication, granting administrator permissions to all access. Use only with --local.

--nobrowser

Does not open a browser after starting. This only takes effect with --local.

Options of the install-project subcommand in addition to --confdir and --dbfile:

Option

Meaning

--name

The project name. If omitted, the name is derived automatically.

--altername

Specifies an alternative name if the name provided with --name cannot be used.

--installifnotfound

Registers the project even if the database file specified with --dbfile does not exist.

1.4.1.4. Initial Configuration

For the Axivion Dashboard Server to function correctly, you must properly prepare your Axivion Suite installation as described here. Most importantly, this means your license key must be installed, and if you are using Linux, you must have executed setup.sh.

First, designate and create a directory outside of the Axivion Suite installation folder for your configuration and log files, then change into this directory using an Axivion command prompt.

Once that is done, execute the following command in the same command prompt:

dashserver init [--confdir config] <TEMPLATE>

which will create a configuration for you from the specified template.

There are several templates available that you can choose from:

SERVER_HTTPS:

Creates a configuration template suitable for a multi-user Dashboard, potentially authenticating users via LDAP or Active Directory. It defaults to using a self-signed certificate. See Securing Communication (TLS/SSL) for more information on this topic.

SERVER:

An alias for SERVER_HTTPS.

SERVER_HTTP:

This is identical to SERVER, except it does not use HTTPS by default. Keep in mind that HTTP traffic is unencrypted; for example, user login passwords are sent in clear text.

LOCALHOST:

Use this to create a “developer-dashboard” running on your local machine for your exclusive access. It does not contain any LDAP or Active Directory related examples.

LOCAL:

An alias for LOCALHOST.

Note

Security and privacy issues occur if other users have access to the CONFDIR. Please read Permissions of the Dashboard Configuration Folder in such a situation.

Note

For security reasons, we recommend not exposing the Dashboard (or a proxy it is running behind) directly to the public internet; instead, we recommend limiting network-level access to your company intranet.

If you do not plan to run multiple Dashboards in the same environment, you may want to set the permanent environment variable AXIVION_DASHBOARD_CONFIG (as indicated by the output of the init invocation) to avoid having to specify the configuration directory in future dashserver invocations.

Inside the configuration directory, you will find the XML file dashboard2.config, which is usually the only dashboard configuration file you need to edit. Its schema follows the classic Axivion Suite configuration schema, consisting only of “Node” and “Binding” elements, but this configuration file does not support layering. Each of these elements must be uniquely identifiable by a slash-separated path (e.g., /dashboard2/EmbeddedTomcat/HttpPort), where the path elements are the values of the “key” attributes of the XML nodes. Every “Binding” node also represents a configuration key, storing its value inside its “value” attribute.

The dashboard2.config file created by the dashserver init command explains the available configuration options and their defaults, and also provides several examples.

For a first test run, you likely do not need to configure anything, as the template you chose should be sufficient for your use case. The values that most often require adjustment are the network- and HTTPS-related configuration options. If you wish to integrate with an external user directory such as Active Directory, you will also need to familiarize yourself with this configuration file.

During startup, the Axivion Dashboard Server creates a file called dashboard2.db inside its configuration folder. This file mainly contains User and Project configuration – specifically, the configuration data that is editable via the web interface. Most importantly, it contains the credentials for the new user required to complete the remaining configuration. This user authenticates with the username “admin” and a randomly generated password. Start the Axivion Dashboard Server using dashserver start --confdir "path/to/dashboard/config"; if this succeeds, you should be able to log in to the Axivion Dashboard Server using the URL and credentials printed on the console.

Caution

Do not forget to change the password of the admin user during initial dashboard configuration.

Note

For a better out-of-the-box experience, the initial admin user is granted more permissions than are necessary for a production setup. For example, consider creating dedicated technical users for uploading new analysis results and removing the associated permissions from the initial admin user.

1.4.1.5. Detailed Configuration

The Dashboard Server

You can handle most configuration needs by adjusting the default values in the dashboard2.config file listed in Figure HTTP Server configuration in dashboard2.config..

HTTP Server configuration in dashboard2.config.
  <Node Key="EmbeddedTomcat">
    <Binding Key="HttpPort" Value="9090" />
    <Binding Key="HttpsPort" Value="9443" />
    <Binding Key="BindAddress" Value="" />
    <Binding Key="DashboardUrlBase" Value="/axivion" />
    <Binding Key="JreHome" Value="$(JAVA_HOME)" />
    <Binding Key="JavaMaxHeapSize" Value="1024" />
    <Binding Key="RuntimeDirectory" Value="../tomcat" />
    <Binding Key="KeyAlias" Value="auto" />
    <Binding Key="KeyStorePath" Value="" />
    <Binding Key="KeyStorePassword" Value="changeit" />
  </Node>
HttpPort

The TCP port users use to access the dashboard via their browsers if HTTPS is not enabled. Defaults to 9090.

HttpsPort

The TCP port users use to access the dashboard via their browsers if HTTPS is enabled. HTTPS is enabled if the KeyAlias option is present in the configuration file; in this case, HttpPort is ignored. Defaults to 9443.

BindAddress

By default, the server listens on all available interfaces. To listen only locally, specify 127.0.0.1.

DashboardUrlBase

Path prefix for the dashboard URL. This may be empty. If you proxy the dashboard, the paths in Tomcat and on the proxy must match.

JreHome

The path to your Java Runtime Environment. If the value remains at its default and the JAVA_HOME environment variable is not specified, the system’s default Java installation will be used.

JavaMaxHeapSize

The heap size of the Tomcat Java process in megabytes. This can be increased if you encounter heap overflows. Defaults to 1024, or 256 for the local Axivion Dashboard Server started with --local.

RuntimeDirectory

The directory where the Tomcat process writes its temporary files.

IPPreference

The IP versions used by the Axivion Dashboard Server. ForceIPv4 disables IPv6; PreferIPv6 prefers IPv6 over IPv4. If left empty, both are enabled and IPv4 is preferred.

DisableHTTP2

If true, Tomcat does not offer HTTP/2. Defaults to false.

HeartbeatInterval

The interval in seconds at which the Axivion Dashboard Server sends a heartbeat event to connected browsers. Defaults to 120; the minimum is 10.

KeyStorePath

The file system path to the server certificate and keystore. Supported keystore types are PKCS #12 (preferred) and JKS.

KeyStorePassword

The password required to access the keystore.

KeyAlias

Identifies the server key to use from the specified keystore. If KeyAlias is set to auto and KeyStorePath is not set, the Dashboard uses HTTPS with a self-signed certificate, generating one if none exists.

Find additional information regarding HTTPS and server identification options in Section Securing Communication (TLS/SSL).

Caution

Ensure that the configured ports are not in use by other services. If they are, adjust the configuration accordingly.

Caution

Changes to these options will only take effect after restarting the dashboard.

Custom Java Variables

To define custom Java variables for the JVM used to run the dashboard, place a file named dashboard.properties in your configuration folder, following the schema in the example below.

Example contents for dashboard.properties
com.example.property1=some example value
com.example.property2=another example value

Custom Environment Variables

To ensure specific environment variables are set for the Axivion Dashboard Server Java process – and any subprocesses it spawns – place a file named dashboard.envvars in your configuration folder, following the schema in the example below.

Example contents for dashboard.envvars
no_proxy=localhost,127.0.0.1,::1

Hint

no_proxy is recognized by the Python requests and urllib libraries used by the Axivion Dashboard Server and its tooling. It holds a comma-separated list of hosts for which any configured HTTP proxy (e.g., via http_proxy/https_proxy) is bypassed. The example above ensures that connections to the local machine are made directly instead of being routed through a proxy.

Caution

Changes to this file will only take effect after restarting the dashboard.

Manual Tomcat Connector Tweaking

The Axivion Dashboard Server uses an embedded Apache Tomcat shipped as part of our product. Note that we use only a small subset of the full Apache Tomcat server and cannot integrate with a pre-existing Apache Tomcat installation.

Caution

This feature is provided for cases where you need to tweak aspects of the Tomcat configuration that are not directly exposed or supported. Changes made here will overwrite the default connector settings and may break dashboard functionality; use this with care.

Tomcat Connector tweaking in dashboard2.config.
  <Node Key="EmbeddedTomcat">
    <Binding Key="HttpPort" Value="9443" />
    ...
    <Node Key="Connector">
      <Binding Key="server" Value="Customized Tomcat Connector" />
      ...
    </Node>
  </Node>

Available binding names can be found in the official Apache Tomcat connector documentation on their website.

Logging

Tomcat and dashboard log files are written to the directory specified by /dashboard2/Logging/Directory.

The Level (the minimum criticality required for a log message to be recorded) has five possible values: debug, info, warning, error, and fatal. Setting this to debug may provide additional information for diagnosing problems.

Logging configuration in dashboard2.config.
  <Node Key="Logging">
    <Binding Key="Directory" Value="../logs" />
    <Binding Key="Level" Value="info" />
    <Binding Key="WriteAccessLog" Value="true" />
    <Binding Key="DaysToKeepAccessLog" Value="30" />
  </Node>

Dashboard log files start with the prefix axivion_. These files are limited to 10 MB; once this limit is reached, they are rotated and backed up with a sequential number up to 5. The most relevant log file is typically axivion_dashboard.log, while tomcat.log is also important. When the dashboard runs as a Windows service (Section Microsoft Windows®), the service wrapper also writes axivion_dashboard_service.wrapper.log, axivion_dashboard_service.out.log, and axivion_dashboard_service.err.log to the logging directory configured during installation, or to the directory specified by --servicelogdir during installation.

Tomcat writes its access log to localhost_access_log.YYYY-MM-DD.txt, with one file per day. WriteAccessLog enables or disables this feature; it defaults to true (and false for the local Axivion Dashboard Server). DaysToKeepAccessLog specifies how many days to retain access log files before they are deleted at startup; it defaults to 30, and a value of 0 retains them indefinitely.

At startup, the Axivion Dashboard Server deletes access log files and files matching axivion_dashboard*.log if they contain passwords or database tokens in logged request URLs. Set SkipEmergencyCleanup to true to prevent this.

Changes to these options will only take effect after restarting the dashboard.

The --loglevel command-line switch for dashserver only sets the level of messages printed to the console before the log files are initialized (e.g., during startup). It does not affect the log file levels.

Further Server Options

The following bindings are direct children of the dashboard2 configuration node. Changes take effect after restarting the dashboard.

Url

The URL the Axivion Dashboard Server uses to refer to itself (e.g., in the startup message and in notification emails). If not specified, the Axivion Dashboard Server derives the URL from the hostname, the port, and DashboardUrlBase. The Dashboard URL in the general settings takes precedence, except for the URL printed at startup.

TerminateOnAbnormalCondition

If true, the Axivion Dashboard Server terminates itself upon an abnormal condition such as insufficient memory, so that a service manager can restart it. Defaults to true.

ForceRelativeRepositoryPath

If true, the Axivion Dashboard Server stores repository clones used for displaying source code in the repositories folder within its configuration folder, even if the project configuration specifies an absolute path. This must be set to true when exporting or importing a project with its repositories. Defaults to false.

Authentication

For authentication configuration, please refer to Dashboard Authentication Configuration.

Securing Communication with other Services

This section provides guidance on securing communication between the dashboard and other services, such as the mail server (see Section General Settings) and potentially an LDAP or Active Directory server (see Section LDAP Configuration Options). To secure communication between your browser and the dashboard, refer to Section Securing Communication (TLS/SSL).

When communicating via LDAP/Active Directory or a mail server, traditional dedicated-port SSL/TLS can be used, or the connection can be initiated via an unencrypted port and upgraded to SSL/TLS via STARTTLS.

As the dashboard is implemented in Java, it relies on the JVM’s Secure Socket Layer (SSL) implementation for creating secure connections. The accepted SSL protocols and cipher suites depend on your JVM. We generally recommend using the latest JVM to ensure that no connections are established using known vulnerable algorithms. Please consult your JVM documentation if you need to change the defaults.

When using authenticated and encrypted connections, the Dashboard requires presented certificates to be trusted. By default, Java uses a JVM-global file containing the trusted certificate authorities (CAs): $(JAVA_HOME)/lib/security/cacerts or $(JAVA_HOME)/lib/security/jssecacerts (if it exists).

If you have your own CA certificate or want to use self-signed certificates, you must add them to that file. For the dashboard, the recommended approach is to create your own trust store file named truststore.jks, place it in your configuration folder, and configure the dashboard to use it as an additional source of trust via Truststore File Path and Truststore Password on the Security > Trusted Certificates page of the general settings. The additional source of trust must be a Java key store in PKCS12 or JKS format; therefore, you should familiarize yourself with the Java command-line tool keytool located at $(JAVA_HOME)/bin/keytool.

As a Dashboard Administrator, you can easily trust your LDAP or Active Directory server’s certificate on the Authentication > LDAP page of the general settings (see Section Authenticator testing). When running one of the authenticator tests, any unknown certificates will be displayed, and you will be asked whether to trust them. If the trust store file does not yet exist, the Dashboard creates it in PKCS12 format, using truststore.jks if no path is configured and the password changeit if no password is configured.

For the mail server, you must currently import certificates manually. To do this, you will need your mail server’s certificate in PEM format. Execute the following command within your dashboard configuration directory:

Trust a PEM public key.
keytool -importcert -keystore truststore.jks \
        -file mailserver-public_key.pem -alias mailserver

If the file truststore.jks does not yet exist, it will be created. keytool asks for the trust store password, which must match the Truststore Password configured in the Dashboard. Note that the certificate must have a “Subject Alternative Name” that matches the hostname the dashboard is connecting to.

If you add a new certificate to your custom trust store or remove an old one, the change will not be automatically detected by new connections. Therefore, you must instruct the dashboard to reload the custom trust store using Reload Certificates on the Security > Trusted Certificates page of the general settings, where the path is also configured.

1.4.1.6. Securing Communication (TLS/SSL)

This section describes how to secure communication between your web browser and the dashboard server. To learn how to secure communication between the dashboard and the various services it uses, refer to Section Securing Communication with other Services.

There are several ways to secure HTTP communication with the Dashboard Server. Tomcat’s built-in HTTPS support can be configured to secure the communication. This is necessary for secure communication if clients connect directly to the Axivion Dashboard Server. Alternatively, you can use a proxy server between the Axivion Dashboard Server and the clients that handles HTTPS connections with the clients. However, it may still be beneficial to use Tomcat’s built-in HTTPS support to protect the communication between the proxy and the Axivion Dashboard Server.

You can achieve this by configuring the corresponding bindings in dashboard2.config:

Tomcat HTTPS configuration in dashboard2.config.
  <Node Key="EmbeddedTomcat">
    <Binding Key="HttpsPort" Value="9443" />
    <Binding Key="KeyStorePath" Value="keystore.p12" />
    <Binding Key="KeyStorePassword" Value="password" />
    <Binding Key="KeyAlias" Value="dashboard" />
    <!-- <Node Key="SubjectAltNames"> -->
    <!--   <Binding Key="1" Value="axivion-dashboard" /> -->
    <!--   <Binding Key="2" Value="axivion-dashboard.example.com" /> -->
    <!-- </Node> -->
  </Node>

If these values are configured, dashboard2/EmbeddedTomcat/HttpPort will be ignored, and Tomcat will only listen for HTTPS requests.

Note

If you switch back to HTTP, you may need to delete cookies in browsers that have previously communicated with the dashboard over HTTPS.

Generating and Using a Self-Signed Certificate

The Axivion Dashboard Server can generate a self-signed certificate by setting the KeyAlias option to auto and leaving the KeyStorePath option unset (e.g., by commenting it out). If the KeyStorePassword is not set in this configuration, the password will be changeit (which does not need to be changed, as this is simply the default password of the Java KeyStore cacerts).

By default, the Axivion Dashboard Server attempts to retrieve the host name from the system. If the result is unsatisfactory, DNS names can be configured using the SubjectAltNames list. Any number of DNS names can be specified, each with an individual key. This key determines the order in the certificate’s Subject Alternative Name list. The first name (based on key ordering) is also used as the Common Name.

During each startup, the Axivion Dashboard Server checks the certificate. If any discovered or configured host names are not part of the current self-signed certificate, a new certificate is generated. The old certificate store is renamed beforehand to prevent data loss. Other generated files (auto.crt and auto.csr) are not backed up, as they can be regenerated using the information in the certificate store.

The validity period is also checked; if the certificate has expired or will expire within the next month, a new one is generated.

Generated Files

Files generated in self-signed certificate mode are stored in the cert directory within the Axivion Dashboard Server configuration directory.

auto.p12

Contains the self-signed CA certificate, the server certificate for the Axivion Dashboard Server, and the server certificate’s private key. The Axivion Dashboard Server uses this file to load the information necessary to establish a TLS connection.

auto.crt

Contains the self-signed CA certificate, which must be installed into the system’s certificate store (OS/browser, Java, Python) to trust the Axivion Dashboard Server.

Caution

Installing auto.crt does not work on macOS: Apple requires TLS server certificates to be valid for at most 825 days. Because the generated server certificate is valid for 10 years, macOS rejects it as “not standards compliant” even if the certificate is explicitly trusted. (The stricter 398-day limit applies only to certificates issued by Root CAs preinstalled with the OS.) On macOS, use REQUESTS_CA_BUNDLE instead.

auto.csr

Certificate signing request (CSR, also called a certification request) used to request a certificate from an official (or company-internal) certificate authority. It contains (among other information) the public key and the list of subject alternative names of the server certificate. The CSR is signed by the private key of the server certificate but does not include it.

Using an official Certificate

Using an official certificate has the advantage of providing encrypted (and authenticated) communication with the Axivion Dashboard Server without the need to deploy the Axivion Dashboard Server certificate to every machine. This means that another authority has already deployed the root certificate, e.g., your IT department.

Caution

The clients require the full certificate chain to validate the trust of the server certificate up to a trusted root certificate. Therefore, it is strongly recommended to include the full chain in the keystore instead of just the server certificate. This allows the Axivion Dashboard Server to provide the chain to the client during the TLS handshake. Including only the server certificate without the full chain will likely cause further configuration effort on every client: the full chain (and not only the root certificate) must be provided for every single client.

Caution

Visual Studio Code uses the system certificate store to retrieve the root certificate (trust anchor). However, it does not read intermediate certificates from the system certificate store. For a working Axivion Visual Studio Code Plugin, it is therefore crucial that the Axivion Dashboard Server delivers the whole certificate chain.

To use an official certificate, several steps are necessary. First, a certificate must be requested. Then, the Axivion Dashboard Server must be configured to use the certificate.

Requesting a Certificate

There are two ways to request a certificate. One way is to create a certificate signing request and send it to your IT department. This ensures that the private key never leaves the machine the Axivion Dashboard Server is running on. The second way is to leave the task of private key generation to your IT department. This way is simpler.

Ask for a Certificate and Private Key

In this variant, your IT department not only generates the certificate (signs the public key) but also generates the private key.

Therefore, a request should ask for the following information:

  • Server certificate

  • Private key corresponding to the server certificate

  • Certificate chain (all intermediate certificates, optionally with the root certificate)

  • Passwords used to protect the private key and/or the certificate store

Request a Certificate via a Certificate Signing Request (CSR)

When requesting a certificate via a CSR, we recommend letting the Axivion Dashboard Server automatically generate a self-signed certificate. This also generates a new private key and a CSR.

  1. Let the Axivion Dashboard Server automatically generate a self-signed certificate.

  2. Send the generated auto.csr to your IT department so that they can sign it (i.e., generate a certificate from it). Be sure to ask not only for the server certificate but also for the whole certificate chain.

  3. After successfully running the certificate wizard to install the new certificate, the automatically generated files are no longer needed.

Using the Certificate Wizard to Create a Key Store and Install it

In the dashboard2.config, the options

  • KeyStorePath

  • KeyStorePassword

  • KeyAlias

must be set; that is, the corresponding lines must not be commented out, although their values may be placeholders.

An example invocation of the certificate wizard looks as follows:

dashserver certificate --confdir path/to/dashboard/config --inputs server.crt private.key chain.pem

The option inputs takes an arbitrary number of files that contain the private keys and certificates. Additionally, system stores are loaded. The order of the files is irrelevant. The type of the files will be determined automatically. Files of different types can be mixed.

If a password is necessary to read a key, the wizard will prompt you to enter it.

Certificates can contain information on where to look for the parent certificate. By default, the certificate wizard does not use this information because it requires loading data from a remote server. When started with the flag --download, the certificate wizard tries to download and use the certificates referenced by other certificates.

After reading the files, the wizard calculates possible certificate chains and prompts you to select the one to be used. The chosen chain will then be stored in a file and dashboard2.config will be updated to use the selected chain. Furthermore, if a root certificate has been found, it is stored in a file that can be used with REQUESTS_CA_BUNDLE or installed into other trust stores.

The paths to the generated files and the dashboard2.config file will be printed to the console.

The wizard can be aborted with Ctrl + c (on German keyboards Strg + c). If this happens before selecting a chain, no configuration changes or files will be written to disk.

Caution

If you are using a self-signed certificate, you will need to take special measures for the communication between the Continuous Integration and the dashboard to work. One way is to set the environment variable REQUESTS_CA_BUNDLE to a path pointing to your certificate in PEM format when invoking axivion_ci. Alternatively, install the certificate into the operating system’s certificate store; see Places to Install the Root Certificate of the Dashboard Certificate. For the automatically generated certificate, this does not work on macOS; see the caution there.

Caution

IDE plugins may also require additional configuration steps to install or use a self-signed certificate. For the Eclipse Plugin, see Section HTTPS connections and for the Visual Studio Plugin, see Section Connection to Axivion Dashboard Server

Caution

The options HttpsPort/HttpPort, DashboardUrlBase, SubjectAltNames, and BindAddress are not checked for consistency. For example, it is possible to configure an DashboardUrlBase with a host that is not covered by the names in the HTTPS certificate.

OpenSSL on Windows

OpenSSL is part of MinGW and Git for Windows. To use these implementations in a MinGW or Git Bash shell, you must run wintty openssl to fix broken stdin/out behavior.

Other OpenSSL binaries for Windows: Binaries - OpenSSLWiki

Test the Axivion Dashboard Server Certificate Configuration

After configuring the certificate for the Axivion Dashboard Server, we recommend testing the setup. The first test is to access the dashboard with a browser. The browser should be able to access it via HTTPS without any certificate, TLS, or SSL warnings.

Once the browser can connect to the Axivion Dashboard Server without issues, a second step is required to verify that the Axivion Dashboard Server provides the certificate chain. This can be done with the OpenSSL command: openssl s_client -showcerts -connect axivion.example.com:9443 . After the TLS handshake, the command expects interactive user input, which will be sent to the server. Consequently, it may appear to hang. Since only the TLS handshake is required, the process can be aborted with Ctrl + c (or Strg + c on German keyboards).

The output should look similar to:

CONNECTED(000001B0)
depth=1 C = US, O = Let's Encrypt, CN = R3
verify error:num=20:unable to get local issuer certificate
---
Certificate chain
 0 s:/CN=axivion.example.com
   i:/C=US/O=Let's Encrypt/CN=R3
-----BEGIN CERTIFICATE-----
[a few lines base64]
-----END CERTIFICATE-----
 1 s:/C=US/O=Let's Encrypt/CN=R3
   i:/C=US/O=Internet Security Research Group/CN=ISRG Root X1
-----BEGIN CERTIFICATE-----
[a few lines base64]
-----END CERTIFICATE-----
---
Server certificate
subject=/CN=axivion.example.com
issuer=/C=US/O=Let's Encrypt/CN=R3
---
[...]

It is important that not only the server certificate is displayed, but also all intermediate certificates. The root certificate may be served by the Axivion Dashboard Server, but this is not required. Providing only the server certificate may prevent clients from building the complete certificate chain.

If the browser connects to the Axivion Dashboard Server via HTTPS without warnings, but OpenSSL shows only the server certificate, it is possible that no intermediate certificates are being used – though this is an unusual configuration. More likely, the browser is retrieving the intermediate certificates from other sources. In this case, we recommend downloading the certificates manually with a browser and starting the certificate wizard again with the downloaded certificates as additional input files.

Places to Install the Root Certificate of the Dashboard Certificate

Windows
  • Double-click auto.crt

  • Press the button Install Certificate...

  • Choose the Store Location: Local Machine installs the certificate for all users but requires administrator permissions.

  • Select the Certificate Store Trusted Root Certificate Authorities

  • Complete the wizard

Debian and Derivatives

Instructions are available in man 8 update-ca-certificates: https://manpages.debian.org/stable/ca-certificates/update-ca-certificates.8.en.html .

Python/CI

The Axivion Suite CI tools (e.g. axivion_ci) verify the Dashboard’s certificate against the operating system’s certificate store (the Windows certificate store, the system CA bundle on Linux, the macOS Keychain). Installing the root certificate into the system’s certificate store as described above is sufficient.

Alternatively, root certificates can be provided via the environment variable:

set "REQUESTS_CA_BUNDLE=<dashboard-configuration-directory>\cert\auto.crt"
Browser
  • Microsoft Edge uses the system certificate store.

  • Firefox uses its own certificate store; however, it can optionally use the system certificate store. https://wiki.mozilla.org/CA:AddRootToFirefox

  • Other browsers may use their own certificate store.

Axivion Visual Studio Plugin

The Axivion Visual Studio Plugin uses the Windows certificate store.

Axivion Visual Studio Code Plugin

Visual Studio Code (and therefore the Axivion Visual Studio Code Plugin) uses the system certificate store. https://code.visualstudio.com/docs/setup/network#_ssl-certificates

Caution

Visual Studio Code uses the system certificate store to retrieve the root certificate (trust anchor), but it does not read intermediate certificates from that store. Therefore, for the Axivion Visual Studio Code Plugin to work, it is crucial that the Axivion Dashboard Server delivers the complete certificate chain.

Java/Axivion Eclipse Plugin

Java uses its own certificate store (.jks Java Keystore), which is also used by Axivion Eclipse Plugin. The installation procedure is described in the Axivion Eclipse Plugin guide: HTTPS connections.

Note

If you encounter certificate or TLS connection problems and require support from Axivion, please include the following information in your support request email:

1.4.1.7. Running the Dashboard behind a Proxy

In many cases, companies have a comprehensive web server setup where SSL certificates, subdomains, and user authentication are already configured, and you simply want the Axivion Dashboard Server to be reachable via this proxy. While this is generally possible, there are several considerations to keep in mind.

URL Base Path

For example, if your proxy serves https://dashboard.example.com/axivion and your dashboard is running on http://some-host:9090/axivion, the URL Base Path is /axivion. This must be identical for both the proxy URL and the proxied URL. See The Dashboard Server on how to configure the URL Base Path.

Dashboard self references

When running behind a proxy, the Axivion Dashboard Server may not always determine the URL it should use to refer to itself. This is most common when sending emails. To specify the correct self-referencing URL, we always recommend configuring the Dashboard URL option (see General Settings) or the Url binding in dashboard2.config (see Further Server Options).

Proxy Authentication

The Dashboard supports proxy authentication where a proxy that has already authenticated the user (e.g., via Basic-Auth) forwards that information via an HTTP header (see Proxy Authentication).

HTTP vs. HTTPS

It is generally preferable to use HTTPS for the dashboard running behind a proxy, both for security and to avoid conflicts with certain security features. Consequently, running an HTTPS dashboard behind an HTTP proxy is not supported. Running an HTTP dashboard behind an HTTPS proxy is functional, although some customers have encountered Invalid CORS request errors in certain browsers. This can occur if the proxy does not inform the Axivion Dashboard Server of the protocol switch (typically via the Forwarded HTTP header), causing the Dashboard to reject the request. If this cannot be configured in the proxy, you can configure the Axivion Dashboard Server to accept its own proxy URL as one of the Origins on the Security > Cross-Origin Resource Sharing page of the general settings.

1.4.1.8. Installing the Dashboard as a System Service

Permissions of the Dashboard Configuration Folder

We strongly recommend running the Dashboard service under an OS user with limited permissions. Running the service as Root, Administrator, or Local System is highly discouraged. dashserver start refuses to start the Axivion Dashboard Server as super user (i.e., as Local System on Windows or with UID 0 on UNIX) unless /dashboard2/AllowRunningAsSuperUser is set to true in dashboard2.config. The Axivion Dashboard Server requires read and write access to its configuration. Please ensure that the OS user running the Dashboard service has these permissions for the config, logs, and tomcat folders (including all subdirectories).

The second aim of the permissions review is to ensure that only the necessary OS users and OS groups (e.g., DashboardUser and the administrator) have access to the configuration folders. The configuration contains security- and privacy- sensitive data, such as usernames, email addresses, and password hashes. An attacker with write access to the configuration can, for example, add new user accounts or change the permissions of Dashboard users. This may also result in arbitrary code execution under the OS user account that runs the Axivion Dashboard Server.

Microsoft Windows®

Note that a Windows service is an isolated process running in its own environment. Consequently, any configuration performed within your session will not be automatically available in the service environment. Examples include authentication keys required to access your version control system or mounted network drives containing dashboard files.

Installation can be performed using the install and uninstall subcommands of the dashserver script. Installing a system service requires elevated privileges; dashserver requests these automatically, so it does not need to be run from an Administrator Command Prompt.

The service is configured to run as the user specified by the --user switch of the install subcommand, which defaults to the user invoking the command. Running the Axivion Dashboard Server under an unprivileged account is strongly recommended, as the service needs little more than to serve HTTP traffic and access its own files.

Warning

Windows® does not allow a service to log on as a named account without a password, and dashserver does not store passwords. The service is therefore installed but cannot be started until you provide the password in the Windows Services console (services.msc), which dashserver install offers to open for you: open the properties of the Dashboard service, switch to the Log On tab, and enter the password for the configured account. Attempting to start the service before this step will fail with The service did not start due to a logon failure (error 1069).

You may also select a different account in the same dialog. The service will then run in that user’s environment. Regardless of the account chosen, ensure it is permitted to read and write the configuration directory, the log files, and the tomcat folder.

If setup is required within the service user’s context, you can do so by using the PreStartCommand and PostStopCommand options in the dashboard2.config file.

An example service setup configuration.
<Configuration Key="dashboard2">
  ..
  <Binding Key="PreStartCommand" Value="net use L: \\fileserver\data" />
  <Binding Key="PostStopCommand" Value="net use L: /delete /yes" />
  ..
</Configuration>

You can also specify the path to a batch file instead of a single command.

Note that if problems occur during service installation, startup, or shutdown, separate log files will be created in the logging directory configured at /dashboard2/Logging/Directory. In some non-standard setups, you may want to place the service log files in a different directory; this can be achieved using the --servicelogdir switch of the install and uninstall subcommands. You can also specify a different Windows service ID using the --id switch.

Note

If you are not using the system default python to run rfgscript, you may need to set the BAUHAUS_PYTHON variable when invoking dashserver install.

GNU/Linux

Preparation

For the Axivion Dashboard Server to function correctly, ensure that your Axivion Suite installation has been properly prepared as described here. Crucially, this means you must have installed your license key and executed setup.sh.

Installation of the Dashboard service itself

Installation can be performed using the install and uninstall subcommands of the dashserver script.

Note that superuser privileges are required to execute the install and uninstall subcommands; therefore, you must run them as root or via sudo.

The --user switch of the install subcommand is required and specifies the OS user under which the service runs. install writes this user, the Axivion Suite installation directory, and the configuration directory to /etc/default/axivion-dashboard, where you can also set JAVA_HOME. If systemd is running, the unit /etc/systemd/system/axivion-dashboard.service is installed and enabled; you start and stop it with systemctl start axivion-dashboard.service and systemctl stop axivion-dashboard.service. Otherwise, it installs the init script /etc/init.d/axivion-dashboard. If the configuration directory does not yet contain a dashboard2.db file, install creates it and prints the initial credentials for the admin user.

If the Axivion Suite is installed for a user axivionuser and you invoke installation or uninstallation from that user’s context, ensure that root has access to the Axivion Suite and the license key. If the license key is placed in the $HOME/.bauhaus folder of the axivionuser, then this can be achieved as follows:

sudo env "PATH=$PATH" "BAUHAUS_CONFIG=$HOME/.bauhaus" dashserver install --user axivionuser --confdir ~/axivion_dashboard/config

Logfile rotation using logrotate

As root, copy BAUHAUS/templates/dashboard-service-linux/etc/logrotate.d/axivion-dashboard to /etc/logrotate.d and adjust the path (and options, if necessary) within the file accordingly to rotate the Axivion Dashboard Server log files.

Putting the Axivion Dashboard Server behind an Apache 2 web server

To place the Axivion Dashboard Server behind an Apache 2 web server, use the Apache 2 configuration file in BAUHAUS/templates/dashboard-service-linux/etc/apache2/sites-available/axivion-dashboard.conf to configure Apache as a proxy to the Axivion Dashboard Server. Depending on your GNU/Linux distribution, the location to copy the configuration file may be different from /etc/apache2/sites-available; please consult the documentation for your distribution.

Putting the Axivion Dashboard Server behind an Nginx web server

To place the Axivion Dashboard Server behind an Nginx web server, use the Nginx configuration file in BAUHAUS/templates/dashboard-service-linux/etc/nginx/sites-available/axivion-dashboard.conf to configure Nginx as a proxy to the Axivion Dashboard Server. Depending on your GNU/Linux distribution, the location to copy the configuration file may be different from /etc/nginx/sites-available; please consult the documentation for your distribution.

Putting the Axivion Dashboard Server behind a Caddy web server

To place the Axivion Dashboard Server behind a Caddy web server, use the Caddy configuration file in BAUHAUS/templates/dashboard-service-linux/etc/caddy/Caddyfile to configure Caddy as a proxy to the Axivion Dashboard Server. Depending on your GNU/Linux distribution, the location to copy the configuration file may be different from /etc/caddy/Caddyfile; please consult the documentation for your distribution.

Running the Axivion Dashboard Server from within a Docker container

You can run the Axivion Dashboard Server from within a Docker container for easier dependency management and better isolation from the host system.

Note

We neither recommend nor discourage the use of a container to run the Axivion Dashboard Server. If your main use case is to isolate dependencies such as Java from those of other services running on the same machine, containerization is a suitable option.

We provide an example Dockerfile to get you started, but you might need to tailor it to your specific Docker setup and host.

example Dockerfile from $AXIVION_INSTALLDIR/templates/dashboard-docker/Dockerfile
# Example Dockerfile for running the Axivion Dashboard in a container.
# Before building or running it, please consult the Axivion
# documentation, which walks through the complete setup.

FROM debian:trixie

ARG DEBIAN_FRONTEND=noninteractive
RUN apt-get update && apt-get install -y \
    openjdk-25-jre-headless \
# ATTENTION: Add the command-line tools for the version control
# systems your projects require. For Git and Subversion projects, for
# example, uncomment the following line:
    # git subversion \
# You may also want a text editor for the Dashboard configuration file
# and tools for debugging the running instance, e.g.:
    # micro htop procps \
    && rm -rf /var/lib/apt/lists/*

# The Axivion Suite archive corresponding with this Dockerfile is
# expected in the build context. Its name contains the version and
# target platform, so there is no sensible default. Pass the archive
# via `--build-arg AXIVION_ARCHIVE=...`; the build fails early if it is
# left unset. Regardless of its file name, the archive extracts to
# /opt/bauhaus-suite.
ARG AXIVION_ARCHIVE
ADD ${AXIVION_ARCHIVE} /opt/
RUN /opt/bauhaus-suite/setup.sh --non-interactive
ENV PATH=/opt/bauhaus-suite/bin:$PATH

# Run the Dashboard as a non-root user whose home directory is the
# data volume below.
RUN groupadd --gid 9000 axivionuser \
    && useradd --uid 9000 --gid axivionuser \
       --home-dir /var/opt/dashboard --create-home \
       --shell /bin/bash axivionuser

# All persistent data lives in a single Docker volume owned by the
# Dashboard user; the Dashboard configuration goes into `config`, the
# license key into `.bauhaus`.
USER axivionuser
RUN mkdir /var/opt/dashboard/config /var/opt/dashboard/.bauhaus
VOLUME /var/opt/dashboard
WORKDIR /var/opt/dashboard

# With this environment variable set, the `dashserver` script locates
# the configuration on its own, so the `--confdir` option need not be
# passed on every invocation inside the container.
ENV AXIVION_DASHBOARD_CONFIG=/var/opt/dashboard/config

# Depending on your configuration (HTTP vs. HTTPS) or reconfigured
# ports, you have to adjust the exposed ports.
EXPOSE 9090 9443

# For a successful start, a valid license key is expected. We
# recommend placing your `*.key` license file into
# `/var/opt/dashboard/.bauhaus/` inside the volume via `docker cp`. To
# update it later, `docker cp` the new key into that directory and
# restart the container (see the documentation).
CMD ["dashserver", "start", "--nodetach"]

This Dockerfile builds on a supported Debian base image and installs only the Java runtime. If you need further tools—such as htop or a text editor—add them to the image before building it.

Important

With this containerized setup, we recommend using only managed_upload projects, whose databases reside inside the volume. If you instead want to use shared_database projects, whose artifacts live outside the container, you are responsible for mounting the relevant host paths into the container and managing their file permissions.

Building the image

Copy the Axivion Suite archive into the build context and build the image as follows:

mkdir -p context
VERSION=X.Y.Z
cp $DOWNLOADS/Axivion-$VERSION-x86_64-gnu_linux.tar.gz context/
docker build \
    --build-arg AXIVION_ARCHIVE=Axivion-$VERSION-x86_64-gnu_linux.tar.gz \
    --tag axivion_dashboard:$VERSION \
    --file $AXIVION_INSTALLDIR/templates/dashboard-docker/Dockerfile context

Note

The AXIVION_ARCHIVE build argument is required and has no default—deliberately, so the image cannot be built against an unexpected or outdated archive. Always pass --build-arg AXIVION_ARCHIVE=... with the exact file name of the archive; the build fails early otherwise.

Note

This builds the Docker image for a specific Axivion Suite version and copies the installation files into the image. Dependencies and package recommendations might change across releases, so it is a good idea to rebuild the image each time you update the Axivion Suite—and to recreate the container from it (see below).

Note

The image creates a user with uid and gid 9000 that runs the Dashboard process with non-root permissions.

Creating the container and its volume

All persistent data—the configuration, the logs, and (for managed_upload projects) the analysis databases—lives in a single, container-managed Docker volume.

First, create the volume and the container (without starting it yet):

docker volume create axivion_dashboard_data
docker create --restart=unless-stopped --name=axivion_dashboard_service --init \
    -v axivion_dashboard_data:/var/opt/dashboard -p 12345:9443 axivion_dashboard:$VERSION

Then copy your license key into the volume. It can have any name as long as it ends in .key:

docker cp $DOWNLOADS/your-license.key axivion_dashboard_service:/var/opt/dashboard/.bauhaus/

Finally, start the container:

docker start axivion_dashboard_service

This should start the Dashboard in the container and create an initial configuration inside the volume.

The arguments used in the docker create command are as follows:

--restart=unless-stopped

Automatically starts the container at system startup and after a crash.

--name=axivion_dashboard_service

Gives the container a meaningful name. Feel free to choose a different one, but the later example commands use this name.

--init

Wraps the Dashboard in an init process that reaps orphaned child processes. This should not be strictly necessary, but it ensures such processes are terminated cleanly if the dashserver script fails to do so.

-v axivion_dashboard_data:/var/opt/dashboard

Mounts the named volume axivion_dashboard_data at /var/opt/dashboard inside the container, which is where the Dashboard keeps its configuration, logs, and the databases of managed_upload projects. All important data thus lives in the volume, not in the container, so the container can be removed and recreated freely (e.g., on upgrades) without data loss.

-p 12345:9443

Maps the host TCP port 12345 to the container port 9443 (the default HTTPS port for a fresh configuration). Adjust this value if you intend to use an existing configuration.

If you followed the example, the login page should be reachable from outside at https://localhost:12345/axivion.

axivion_dashboard:$VERSION

Name of the image built above, which we use to create the container. $VERSION is the shell variable set before building the image.

We can now use various commands to further manage our container:

docker stop axivion_dashboard_service

Stops the container.

docker start axivion_dashboard_service

Starts the container again.

docker restart axivion_dashboard_service

Restarts the container, e.g., to apply configuration changes.

docker logs axivion_dashboard_service

Prints the container’s output, which includes the initial administrative credentials. Do not forget to change them from within the Axivion Dashboard Server.

docker exec -it axivion_dashboard_service bash

Opens a shell inside the container, e.g., to run dashserver restore-admin (to reset the admin password).

Configuring the dashboard

All configuration lives inside the volume, and by default the image ships without an editor. To change the configuration, copy the file out of the container with docker cp, edit it on the host, and copy it back. The configuration directory inside the container is /var/opt/dashboard/config:

docker cp axivion_dashboard_service:/var/opt/dashboard/config/dashboard2.config dashboard2.config
# edit dashboard2.config on the host with an editor of your choice
docker cp dashboard2.config axivion_dashboard_service:/var/opt/dashboard/config/dashboard2.config

After changing the configuration, restart the container for the changes to take effect:

docker restart axivion_dashboard_service

If you added a text editor to the image, e.g., micro, you can instead edit dashboard2.config in place. Inside the container the configuration directory is available as $AXIVION_DASHBOARD_CONFIG:

docker exec -it axivion_dashboard_service \
    sh -c 'micro "$AXIVION_DASHBOARD_CONFIG/dashboard2.config"'

Restart the container afterwards.

Note

docker cp writes the copied files with root ownership. The Dashboard can still read them, so this does not affect its operation. To edit such a file inside the container—for example, after copying one back in with docker cp—you must fix its ownership first:

docker exec -u 0 axivion_dashboard_service \
    sh -c 'chown axivionuser:axivionuser "$AXIVION_DASHBOARD_CONFIG/dashboard2.config"'

Updating the license key

When you receive a new license key, copy it into the .bauhaus directory and restart the container:

docker cp $DOWNLOADS/new-license.key axivion_dashboard_service:/var/opt/dashboard/.bauhaus/
docker restart axivion_dashboard_service

Fixing the auto-generated TLS certificate

By default, the Dashboard generates a self-signed certificate for the hostname it detects from the system. Inside a container, this is the container-internal hostname, which is not reachable from outside—so the default HTTPS certificate does not match the address your users actually use. To fix this, add the externally visible host name (the Docker host’s domain/hostname) to the SubjectAltNames of the certificate configuration.

Edit dashboard2.config as described above (copy it out using docker cp, modify it, and copy it back), setting SubjectAltNames inside the EmbeddedTomcat node as follows (using the Docker host’s name):

<Node Key="SubjectAltNames">
  <Binding Key="1" Value="dashboard.example.com" />
</Node>

Then restart the container. Upon the next startup, the Dashboard detects the changed host name and regenerates the certificate accordingly:

docker restart axivion_dashboard_service

For a complete TLS setup, you typically need to transfer the generated certificate files between the container and the host using docker cp. The files reside in the cert directory of the configuration (see here):

# Copy the self-signed CA certificate out, e.g., to trust the
# Dashboard via REQUESTS_CA_BUNDLE or by installing it into the
# system's certificate store.
docker cp axivion_dashboard_service:/var/opt/dashboard/config/cert/auto.crt auto.crt

# Copy the certificate signing request out, e.g., to hand it to
# your IT department.
docker cp axivion_dashboard_service:/var/opt/dashboard/config/cert/auto.csr auto.csr

1.4.1.9. FAQ

Q: Why do I get SSL certificate errors after upgrading to Axivion 7.11?

A: Axivion 7.11 bundles Python 3.13, which enforces stricter SSL certificate validation, requiring the “critical” flag on CA certificates. Self-signed certificates generated by older dashboard versions lack this flag.

Solutions:

  1. Update to the latest dashboard version that generates certificates with the required critical flag. The Axivion Dashboard Server continues to use an existing, valid cert/auto.p12, so delete or rename it in the configuration directory and restart the Axivion Dashboard Server to generate a new certificate. Then install the new cert/auto.crt into the certificate stores of the clients again.

  2. Use the BAUHAUS_PYTHON environment variable to specify an older Python version (temporary workaround).

  3. Investigate your SSL/TLS infrastructure to ensure proper certificate handling.

Q: When running the analysis in a Docker container and the dashboard is running on the host, how can I access it?

A: Use the host name host.docker.internal with the protocol and port of your dashboard, e.g., https://host.docker.internal:9443/axivion. With HTTPS, the dashboard’s certificate must contain host.docker.internal, e.g., via SubjectAltNames for the self-signed certificate.