This page explains the configuration options for the **SMP server version 8.x**.

All properties are supposed to be located in the file `application.properties` which resides by default in the `src/main/resources` folder of the `phoss-smp-webapp-(mongodb|sql|xml)` project (which is `WEB-INF/classes` in the compiled version).
The configuration file uses UTF-8 as their default encoding.

All configuration properties are resolved according to the rules described in https://github.com/phax/ph-commons/wiki/ph-config

**Note**: since the default Java properties file handling is used to read the configuration 
file recall that trailing whitespaces of a property name and leading white spaces of a 
property value are automatically skipped. **Trailing whitespaces of a property value are not skipped!**

**Table of Contents**

* [Database Configuration (SQL)](#db)
* [General Configuration](#general)
* [SMP Frontend Configuration](#frontend)
* [SMP Backend Configuration](#backend)
* [GUI Managable Settings](#gui)
* [Directory Client Configuration](#directory)
* [HTTP Proxy Configuration](#httpproxy)
* [Type of Backend Specific Configuration](#backendtype)
    * [SQL Backend Specific Configuration](#sql)
        * [PostgreSQL Specific Configuration](#postgresql)
    * [XML Backend Specific Configuration](#xml)
    * [MongoDB Backend Specific Configuration](#mongodb)
* [Internal Error Handling Configuration](#internalerror)

# <a name="db"></a>Database Configuration (SQL)

This project was tested with MySQL 5.x, 8.x and PostgreSQL 13, 14 as a backend and it works without problems. Additionally phoss SMP was tested with particular instances of Oracle and DB2 but the author cannot provide any real support for these database systems.

The database is automatically created via a built-in [Flyway](https://flywaydb.org/) database versioning engine.
Since v6.0.0 the latest Flyway version (9.x at the time of writing) is used which e.g. does NOT support MySQL 5.7 anymore.

Note: Some tables of the MySQL database are setup using `latin` collation, because the keys used internally would (when using `utf8`) exceed the maximum length of 767 characters. This is a legacy problem because the data structures from the original CIPA SMP are re-used.

# <a name="general"></a> General Configuration

This section contains some general purpose configuration properties

* **`global.debug`**: overall debug mode. This enables additional checks that should not be executed every time (e.g. because they are slow or because they are spamming the logfile etc.). This flag has no impact on the logging level! This flag should be set to `true` in development mode, but to `false` in production mode. The value of this field is internally maintained in class `com.helger.commons.debug.GlobalDebug`.
* **`global.production`**: overall production mode. If this flag is set to `false` certain functionality not applicable in development environment (like mass mail sending) is disabled. This flag should be set to `true` in production mode.
* **`global.debugjaxws`**: globally enable or disable Webservice API logging. To enable debug logging, set this value to `true`. If set to `false` debug logging is disabled. The default value is `false` and in production systems this should be set to `false` as well. Recommendation: enable this flag only temporarily for debugging purposes.

# <a name="frontend"></a> SMP Frontend Configuration

This section contains the configuration properties that are focuses on the frontend of phoss SMP

* **`webapp.datapath`**: the path where all relevant data and settings are stored. This can e.g. be a relative path (like `conf` - relative to the web application directory) for development purposes but should be an absolute path (e.g. `/var/www/smp/data`) in production. Make sure the user running the SMP has write access to this folder.
* **`webapp.checkfileaccess`**: a flag that determines whether the directory of the web application should be checked for read and write access. This is only required if the data path inside the web application and should therefore always be `false`.
* **`webapp.testversion`**: a special indicator for the web application whether the version should be highlighted as a "test" version. Set to `true` in debug mode and `false` in production mode.
* **`webapp.statistics.persist`**: `true` to enable the persistence of usage statistics when shutting down, `false` to not store the statistics. The default value is `true`.
* **`webapp.directory.name`**: set this property to change the name of the Directory implementation on the user interface. By default "Peppol Directory" is used, but it maybe "TOOP Directory" for TOOP etc. - there are no limits on the name. This configuration item has no functional implications.
* **`webapp.servicegroups.extensions.show`**: `true` to show the content of the extensions in the service group list in the administrative area. Default is `false`.
* **`webapp.security.login.errordetails`**: enable or disable the display of error details on failed logins via the UI. When disabled, all login failures (unknown user, wrong password, disabled user, etc.) show the same generic error message, so that it cannot be determined, whether a specific user exists or not. The default value is `false` since v8.5.0 - up to and including v8.4.3 the default value was `true` for backwards compatibility reasons.
* **`webapp.public.showappname`**: `true` to show application name, application version and supported API on the public page, `false` to hide it. Default is `true`. The information is always shown in the administration part.
* **`webapp.public.showsource`**: `true` to show the link to the GitHub project on the public page, `false` to hide it. Default is `true`. The link to the source is always shown in the administration part.
* **`webapp.public.showauthor`**: `true` to show authorship on the public page, `false` to hide it. Default is `true`. The authorship is always shown in the administration part.
* **`webapp.logo.inline`** (since v6.0.0): an optional [data URL](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/Data_URLs) that contains an image that will be used as the application logo.
* **`webapp.logo.externalurl`** (since v6.0.0): an optional absolute external URL (starting with `http` or `https`) that references an image that will be used as the application logo. If this is used, make sure the CORS HTTP headers are set correctly.
* **`webapp.logo.internalurl`** (since v6.0.0): an optional relative internal URL (starting with `/`) that references an image that will be used as the application logo. If this is used, make sure it is resolved correctly on the application host.
* **`webapp.nicename.doctypes.path`**: the file system path to an XML file that contains a mapping from document type identifiers to nice display names. By default an internal list is loaded. See below for the layout of the XML file. See also [[Custom Nice Names]].
* **`webapp.nicename.processes.path`**: the file system path to an XML file that contains a mapping from process identifiers to nice display names. By default an internal list is loaded. See below for the layout of the XML file. See also [[Custom Nice Names]].
* **`webapp.imprint.enabled`**: `true` to enable the printing of a custom imprint in the footer of every page 
* **`webapp.imprint.text`**: the text to used for the imprint. This setting is mandatory if an imprint should be shown. This is only evaluated if `webapp.imprint.enabled` is set to `true`.
* **`webapp.imprint.href`**: an optional link target for the imprint. This must be a valid URL using the "http" or "https" scheme. The imprint text is shown even if no href is provided. Example value: `https://www.google.com`
* **`webapp.imprint.target`**: the optional link target for the imprint. This is only evaluated if `webapp.imprint.href` is present. By default the link opens in the current window. Example value: `_blank`.
* **`webapp.imprint.cssclasses`**: an optional whitespace separated list of CSS classes that are applied on the imprint HTML node (`<span>` for text only or `<a>` if a link href is present). Only existing CSS classes from Bootstrap 5 can be used (up to and including v8.1.8 it was Bootstrap 4). Example value: `mx-3 badge text-bg-primary` (the Bootstrap 4 equivalent was `mx-3 badge badge-primary`).
* **`webapp.page.admin.monitoring.sessions.disabled`** (since v6.0.0): disables the availability of the "Administration | Monitoring | Sessions" page, that may be deemed insecure due to having session IDs in the URL. By default is is enabled.
* **`webapp.page.admin.sysinfo.envvars.disabled`** (since v6.0.8): disables the availability of the "Administration | System Information | Environment Variables" page, that may be deemed insecure due to having secrets in env Vars. By default is is enabled.
* **`webapp.systemmsg.usemarkdown`** (since v6.0.1): enables or disables the usage of Markdown (MD) for system messages. By default is is `true`.  
* **`webapp.session.cookie.secure`** (since v8.5.0): determines whether the session cookie (`JSESSIONID`) should have the `Secure` flag, so that a browser only sends it via https. Possible values are `true`, `false` and `auto`. The default value is `auto`, which enables the flag, if `smp.publicurl` is an `https` URL, and which leaves the flag untouched otherwise - so an existing setting from the `web.xml` or from the application server is only overruled with the explicit values `true` and `false`. Set this to `false`, if the management GUI must also be reachable via plain http.
* **`webapp.session.cookie.samesite`** (since v8.5.0): the value of the `SameSite` attribute of the session cookie (`JSESSIONID`), that determines whether a browser sends the cookie on cross-site requests. Possible values are `Strict`, `Lax` and `None` (case insensitive). The default value is `Strict`. Use an empty value to not touch the attribute at all, so that only the `web.xml` or the application server determine it. Note that a browser rejects a cookie with `SameSite=None`, if it is not marked as `Secure` as well - see `webapp.session.cookie.secure`.
* **`http.method.options.disabled`**: enable or disable support for the HTTP OPTIONS verb. By default it is enabled.
* **`csp.enabled`**: enable or disable the output of the "Content Security Policy" HTTP headers. By default this is enabled.
* **`csp.reporting.only`**: enable or disable the reporting of CSP issues only. So no content will be blocked if CSP is enabled but a CSP violation is found. By default this is disabled. The reporting URI inside the SMP is always `/smp-cspreporting`.
* **`csp.reporting.enabled`**: enable or disable the reporting of CSP issues if something is blocked. This only has an effect, if `csp.enabled` is `true` and `csp.reporting.only` is `false`. By default this is disabled. The reporting URI inside the SMP is always `/smp-cspreporting`.

## Previous configuration properties

* **`webapp.public.login.enabled`** (removed in v7.2.6): `true` to show a login UI element on the `/public` application part, `false` to not show it. The default value is `true`.

# <a name="backend"></a> SMP Backend Configuration

The following list describes all the possible configuration items related to the functioning as an SMP server.

* **`smp.backend`**: The backend to be used. Can either be `sql`, `xml` or `mongodb` - depending on the binary you picked. Any other value will result in a startup error.
* **`smp.keystore.type`**: The type of the keystore. Can either be `JKS`, `PKCS12` or `BCFKS`. The value is case insensitive. The default value is `JKS`.
* **`smp.keystore.path`**: The classpath - relative to the project - where the Java key store with the SMP certificate is located. An empty directory `src/main/resources/keystore` is present which could contain the key store. In this case the properties entry should start with `keystore/`. This may also be an absolute path to a file where the keystore is located.
    <br>**Note:** The key store should contain exactly one certificate entry with an arbitrary name (aka alias, see `smp.keystore.key.alias`) and the key should have the same password (see `smp.keystore.key.password`) as the whole key store!
* **`smp.keystore.password`**: The password used to access the key store as a whole.
* **`smp.keystore.key.alias`**: The alias of the key within the key store. Is case sensitive and may not be empty. The key behind the alias is used to sign certain response messages.
* **`smp.keystore.key.password`**: The password of the key with the above specified alias. Should be the same as the password of the whole key store (see `smp.keystore.password`).
* **`smp.truststore.type`**: The type of the trust store. Can either be `JKS`, `PKCS12` or `BCFKS`. The value is case insensitive. The default value is `JKS`.
* **`smp.truststore.path`**: The classpath - relative to the project - where the trust store with the public certificates of the servers to communicate with (e.g. SML and Directory) are contained. This property is optional. If no trust store path is provided, the SML client caller trusts all TLS certificates.
* **`smp.truststore.password`**: The password used to access the trust store. This property is optional.
* **`smp.forceroot`**: It indicates, whether all internal paths should be forced to root ("/").
    This is a flag which may either have the value `true` or `false`.
    This is especially helpful, when the application runs in a Tomcat application context (e.g. "/smp") but is proxied to a different domain via a reverse proxy (like httpd or nginx).
* **`smp.publicurl`**: this optional property allows you to define the absolute server URL by which the SMP is accessible from the outside. This is helpful when the SMP runs on an application server (like Tomcat) that is proxied by a web server (like httpd or nginx) to pass out the correct name in SMP responses that require absolute URLs. This URL should *NOT* end with `/public`.
    <br>**Note:** since v6.0.8 it is checked, that this value is a valid URL. If not, the server refuses to start up. Of course, this value is still optional. 
* **`smp.publicurl.mode`**: determine how the ServiceGroup domain names in the REST calls to `GET /{serviceGroup}` should be rendered. Possible values are:
    * `default` - uses the value of the `smp.publicurl` as the domain name
    * `request` - uses the protocol and hostname of the current request as the domain name
    * `x-forwarded-header` (since v7.2.8) - uses the HTTP headers `X-Forwarded-Proto`, `X-Forwarded-Host` and `X-Forwarded-Port` to build the base server name. A missing protocol or host is taken from the incoming request. A missing `X-Forwarded-Port` leads to the usage of the default port of the used protocol, except if neither `X-Forwarded-Proto` nor `X-Forwarded-Host` is present - in that case the port of the incoming request is used (fixed in v8.3.0)
    * `forwarded-header` (since v7.2.8) - uses the HTTP header `Forwarded` to build the base server name
* **`smp.identifiertype`**: determine the identifier types to be used. Possible values are (the default is `peppol`):
    * `simple` - all identifier schemes and values are accepted
    * `peppol` - the special stricter Peppol rules for identifiers are applied
    * `peppol-lax` - loosened (lax) Peppol rules for identifiers are applied (since v7.1.2)
    * `bdxr1` - the OASIS BDXR SMP v1 identifier rules are applied (old value: `bdxr`)
    * `bdxr2` - the OASIS BDXR SMP v2 identifier rules are applied
    * `dbnalliance` - the DBNAlliance identifier rules are applied (since v8.1.7). Behaves like `bdxr2` but treats Document Type and Process Identifiers as case insensitive regardless of the scheme, matching the DBNAlliance interpretation of the OASIS BDXR SMP v2.0 specification
* **`smp.rest.type`**: this property determines the layout of the REST responses. Possible values are (the default is `peppol`):
    * `peppol` - the returned XML data corresponds to the Peppol SMP specification (XML namespace URI `http://busdox.org/serviceMetadata/publishing/1.0/`)
    * `bdxr` - the returned XML data corresponds to the OASIS BDXR SMP v1 specification (XML namespace URI `http://docs.oasis-open.org/bdxr/ns/SMP/2016/05`)
    * `bdxr2` - the returned XML data corresponds to the OASIS BDXR SMP v2 specification (XML namespace URIs `http://docs.oasis-open.org/bdxr/ns/SMP/2/ServiceGroup` and `http://docs.oasis-open.org/bdxr/ns/SMP/2/ServiceMetadata`)    
* **`smp.rest.log.exceptions`**: this property enables or disables the detailed logging of exceptions that occur while processing REST calls. By default the logging is disabled.
* **`smp.rest.payload.on.error`**: this property enables or disables the provision of HTTP response contents in case of errors from the REST API. By default this is enabled (for backwards compatibility), but for security reasons this might be disabled.
* **`smp.rest.delete.notfound.as.ok`** (since v8.1.0): this property enables or disables the idempotent handling of HTTP DELETE requests. When enabled, DELETE requests targeting non-existing entities return HTTP 204 (No Content) instead of HTTP 404 (Not Found). By default this is disabled.
* **`smp.rest.auth.errordetails`** (since v8.2.0): this property enables or disables the detailed error messages of failed REST API authentications. When disabled, all authentication failures (unknown user, deleted user, invalid password, disabled user, unknown Bearer token) return the same generic error message, so that it cannot be determined, whether a specific user exists or not. By default this is enabled (for backwards compatibility), but for security reasons it should be disabled. The detailed reason is always logged on the server, independent of this setting.
* **`smp.rest.cache.enabled`** (since v8.6.1): this property enables or disables the caching of the responses of the read-only REST API endpoints `GET /{ServiceGroupId}` and `GET /{ServiceGroupId}/services/{DocumentTypeId}`. A cached Service Metadata response is already signed, so neither the backend is queried nor is the response signed again. This is an opt-in feature, so by default it is **disabled**. All cached responses of a participant are removed as soon as its Service Group, a Service Information or a Redirect is modified on the same SMP instance; bulk endpoint URL or certificate changes and a reload of the SMP key store remove all cached responses. The cache is local to each SMP instance - in a multi-instance setup a modification on one instance becomes visible on the other instances at the latest after `smp.rest.cache.ttl`. Changing this property requires a restart. The storage can be replaced by providing exactly one implementation of the SPI interface `com.helger.phoss.smp.restapi.cache.ISMPRestResponseCacheSPI` - by default an in-memory cache is used.
* **`smp.rest.cache.ttl`** (since v8.6.1): the time a single REST API response is cached. This is also the maximum time until a modification is visible on other SMP instances. Missing, zero or negative values result in the default value of `60s`.
* **`smp.rest.cache.maxitems`** (since v8.6.1): the maximum number of cached REST API responses per SMP instance. Each Service Group response (per public URL) and each Service Metadata response (per document type) counts as one item. The default value is `10000`. Use `0` or a negative value for an unlimited size.
* **`smp.rest.remote.queryapi.disabled`**: this property enables or disables the availability of the remote query API, that allows to query remote SMPs for all document types, service information and business cards. By default this is disabled.
* **`smp.status.enabled`**: this property can be used to enable or disable the status API at `/smp-status/`. By default the status API is enabled.
* **`smp.status.sql.enabled`**: this property can be used to enable or disable the SQL backend specific status items. This is especially relevant as a negative SQL connectivity check can take quite some time, which will contradict the usage of `/smp-status` for health checking purposes.
* **`smp.status.show.certificate.dates`**: if this property is `true`, the status items `smp.certificate.notbefore` and `smp.certificate.notafter` are shown in the `/smp-status` data
* **`smp.ready.timeout`** (since v8.4.0): the maximum duration a readiness check at `/smp-ready` may take, before the SMP is considered to be not ready. This ensures that a readiness request never blocks an HTTP thread for an unbounded amount of time - e.g. because the database became silently unreachable. The default value is `2s`. Use `0` or a negative value to run the checks without a time limit. See the [[Readiness API]] page for details.
* **`smp.export.retention.days`** (since v8.3.0): the number of days a Service Group export file created from the management UI is kept in the `servicegroup-export` directory below the data path (see `webapp.datapath`), before it is deleted. The default value is `30` (roughly one month). Use `0` or a negative value to keep the export files forever. Outdated files are deleted by a scheduled job that runs once a day at 02:00, and additionally whenever a new export is started.
* **`smp.totp.enabled`** (since v8.4.3): this property enables or disables the two-factor authentication (TOTP) of the management GUI. This is an opt-in feature, so by default it is **disabled**. While it is disabled, the pages *Administration / Two-factor authentication* and *Administration / Two-factor authentication of all users* are not created at all - and are therefore also not reachable by URL - and existing enrollments are not enforced on login. The enrollments themselves are retained, so they become effective again as soon as this property is enabled. Changing this property requires a restart. See the [[Security]] page for details.
* **`smp.totp.issuer`** (since v8.4.3): this property defines the issuer that is shown in the authenticator app of a user, identifying this SMP instance.
    <br>If it is not set, the application title is used - so every phoss SMP installation shows up with the same name, which is inconvenient if you administer more than one of them.
    <br>A value like `SMP smp.example.org` makes the entries distinguishable.
    <br>**Note:** the value must not contain a colon, because that is the separator between the issuer and the account name.
    <br>**Note:** it only has an effect on newly created enrollments - an already enrolled authenticator keeps the name it was set up with.
* **`smp.timezone`**: this property can be used to set the default time zone in which the SMP operates. By default it is `UTC` (aka Greenwich Mean Time / GMT) but any other time zone name like `Europe/Vienna` is also possible. The exact list of available time zones depends on the Java version that is used. If the provided value is incorrect, the SMP wont start up.
* **`smp.bdxr2.certificate.mimecode`**: this property defines the value of the Endpoint Certificate `mimeCode` attribute. The default value is `application/base64`. This property is only evaluated if the `smp.rest.type` is `bdxr2`.
* **`smp.bdxr2.certificate.typecode`**: this property defines the value of the Endpoint Certificate `TypeCode` element. The default value is `bdxr-as4-signing-encryption`. This property is only evaluated if the `smp.rest.type` is `bdxr2`.
* **`sml.smpid`**: The SMP ID to use when using the SML interface.
    <br>**Note:** it must be the same ID that was used for the initial registration of the SMP to the SML.
    <br>**Note:** is only required if the entry `sml.enabled` is set to `true`.
* **`sml.smp.ip`**: this property defines the default value for the field *physical address* in the SMP to SML registration process and must contain the public IP address of the SMP server (e.g. like `1.2.3.4`). If this property is not set the field must explicitly entered during the registration process.
    <br>**Note:** has only effect if the entry `sml.enabled` is set to `true`.
* **`sml.smp.hostname`**: this property defines the default value for the field *logical address* in the SMP to SML registration process and must contain the public hostname of the SMP server (e.g. like `smp.example.org` or `http://smp.example.org`). If this property is not set the field must explicitly entered during the registration process.
    <br>**Note:** has only effect if the entry `sml.enabled` is set to `true`.
* **`sml.connection.timeout`** (since v8.1.8): if this property is present it sets the connect timeout to the configured SML. Accepts the duration grammar (e.g. `5s`, `1m 30s`). Default is unset (the system default timeout is used).
    <br>**Note:** is only required if the entry `sml.enabled` is set to `true`.
    <br>**Note:** the legacy millisecond-typed key `sml.connection.timeout.ms` is still honored but deprecated for removal; a deprecation warning is logged (once) when it is used.
* **`sml.request.timeout`** (since v8.1.8): if this property is present it sets the response timeout to the configured SML. Accepts the duration grammar (e.g. `20s`, `1m 30s`). Default is `30s`.
    <br>**Note:** is only required if the entry `sml.enabled` is set to `true`.
    <br>**Note:** the legacy millisecond-typed key `sml.request.timeout.ms` is still honored but deprecated for removal; a deprecation warning is logged (once) when it is used.
* **`smp.hredelivery.extension`** (since v8.0.6): if set to `true`, it will create the necessary SMP Extension element with ID `eRacunParticipantData`. Default is `false`.
    <br>**Note:** this only works, if the `smp.rest.type` is set to `bdxr`.
* **`smp.hredelivery.accesspointoib`** (since v8.0.6): This must be the Croatian OIB number of the Access Point operator. This must be an 11-digit number. This value is only evaluated, if `smp.hredelivery.extension` is set to `true`.

## Previous configuration properties

* **`hredelivery.sg.extension.on.si`** (since v8.0.1; deprecated in v8.0.6; removed in v8.1.0): if set to `true`, any eventually present Extension on a Service Group will be used as the extension on the Service Information REST API. Default is `false`. Use the `smp.hredelivery.extension` property instead.
    <br>**Note:** this only works, if the `smp.rest.type` is set to `bdxr`

## <a name="gui"></a> GUI managable settings

The following properties can be managed on the GUI.
The configuration properties are only read initially as the default values.
Afterwards changes to the configuration properties have no impact on the settings.

* **`smp.rest.writableapi.disabled`** (since 4.0.2): this property can be used to programmatically disable the non-standard writable REST APIs. If they are invoked an HTTP 404 is returned if this flag is set to `true`. This property may have only the values `true` or `false`. If not specified, the default value is `false` meaning that the writable REST API is enabled (as it always was).
* **`sml.required`** (since 6.0.0; previously `sml.needed`): This fields indicates, if an SML connection is expected and triggers the display of warnings if the SML connection is disabled. If this field is `true` and `sml.enabled` field is `false` warnings are displayed on the UI.
* **`sml.enabled`** (since 6.0.0; previously `sml.active`): This field indicates, whether connection to the SML is active or not.
    This is a flag which may either have the value `true` or `false`.
    For testing purposes you may set it to `false` to disable the communication with the SML. For production the value must be `true` so that all relevant creations, updates or deletions of participants are communicated to the SML which will create/modify/delete the respective DNS entries.
* **`smp.directory.integration.required`** (since 6.0.0; previously `smp.peppol.directory.integration.required`): This fields indicates, if a Directory connection is expected and triggers the display of warnings if the Directory connection is disabled. If this field is `true` and `smp.peppol.directory.integration.enabled` field is `false` warnings are displayed on the UI.
* **`smp.directory.integration.enabled`** (since 6.0.0; previously `smp.peppol.directory.integration.enabled`): set this property to `true` to activate the Directory Business Card Features
* **`smp.directory.integration.autoupdate`** (since 6.0.0; previously `smp.peppol.directory.integration.autoupdate`): automatically update the Directory server, if something changes in the business card. This feature can be changed on the UI of the SMP.
* **`smp.directory.hostname`** (since 6.0.0; previously `smp.peppol.directory.hostname`): the fully qualified host name of the Directory server. Defaults to `https://directory.peppol.eu`.

# <a name="directory"></a> Directory Client Configuration

See https://github.com/phax/phoss-directory/#client-configuration-properties for all Directory client configuration items

# <a name="httpproxy"></a> HTTP Proxy Configuration

The following settings are only needed, when running the SMP behind a proxy server.
These properties e.g. affect the communication with the SML and the Directory.

* **`http.proxyHost`**: Proxy host name or IP address for HTTP connections
* **`http.proxyPort`**: Port number of the proxy host to use for HTTP connections
* **`https.proxyHost`**: Proxy host name or IP address for HTTPS connections
* **`https.proxyPort`**: Port number of the proxy host to use for HTTPS connections
* **`proxy.username`**: Optional user name for the proxy server.
* **`proxy.password`**: Optional password for the user on the proxy server

**Note**: make sure to set both `http.` and `https.` properties - this is related to the target server to connect and not the hosting of the SMP.

**Note**: If Directory is used, ensure that your `application.properties` file also contains the respective HTTP proxy configuration items as outlined in https://github.com/phax/phoss-directory/#pd-client

# <a name="backendtype"></a> Type of Backend Specific Configuration

## <a name="sql"></a> SQL Backend Specific Configuration

When the **SQL** backend is used, the following properties are also available:

* **`jdbc.driver`**: The JDBC driver class to be used by JPA. For MySQL use `com.mysql.jdbc.Driver`.
* **`jdbc.url`**: The JDBC URL of the database to connect to. For a local MySQL database called "smp" the string would look like this: `jdbc:mysql://localhost:3306/smp?autoReconnect=true`
  <br>**Note:** the URL depends on the JDBC driver used!
* **`jdbc.user`**: The database user to be used when connecting to the database.
* **`jdbc.password`**: The password of the JDBC user to be used when connecting to the DB
* **`jdbc.schema`**: The database schema to be used when connecting to the DB. The default value is `smp`.
* **`jdbc.schema-create`**: **Deprecated since 8.1.4** - prefer using `smp.flyway.jdbc.schema-create` instead. This key is still supported as a fallback.
* **`jdbc.database-type`** (since 8.1.4): The target database type to be used.
  <br>For MySQL this should be `MySQL`.
  <br>For PostgreSQL this should be `PostgreSQL`
  <br>For Oracle this should be `Oracle`
  <br>For DB2 this should be `DB2`
  <br>For MS SQLServer this should be `SQLServer`
  <br>**Note:** this is not the name of the database schema. That name is part of the `jdbc.url`.
* **`target-database`**: **Deprecated since 8.1.4** - prefer using `jdbc.database-type` instead. This key is still supported as a fallback.
* **`jdbc.execution-time-warning.enabled`**: enable or disable the logging of long running JDBC transactions. Set this value to `true` to enable logging of long running JDBC transactions and `false` to disable it. By default these warnings are enabled.
* **`jdbc.execution-time-warning`**: the duration after which a warning will be emitted if a JDBC transaction takes longer. Accepts the duration grammar (e.g. `5s`, `1m 30s`). This only has an effect if the configuration item `jdbc.execution-time-warning.enabled` evaluates to `true`. The default value is `1s`.
    <br>**Note:** the legacy millisecond-typed key `jdbc.execution-time-warning.ms` is still honored but deprecated for removal (via ph-db); a deprecation warning is logged (once) when it is used. See [#492](https://github.com/phax/phoss-smp/issues/492).

* **`jdbc.pooling.max-connections`** (since 8.0.11): The maximum number of active connections that can be allocated from the pool at the same time, or negative for no limit. Default is `8`.
* **`jdbc.pooling.max-wait.millis`** (since 8.0.11): The maximum number of milliseconds that the pool will wait (when there are no available connections) for a connection to be returned before throwing an exception, or `-1` to wait indefinitely. Default is `10000` (10 seconds).
  <br>Prior to v8.0.11 the default waiting time default value was `-1` meaning indefinite waiting.
* **`jdbc.pooling.between-evictions-runs.millis`** (since 8.0.11): The number of milliseconds to sleep between runs of the idle object evictor thread. When non-positive, no idle objects are evicted. `300000` (5 minutes).
  <br>In v8.0.11 the default was `-1`.
* **`jdbc.pooling.min-evictable-idle.millis`** (since 8.0.11): The minimum amount of milliseconds an object may sit idle in the pool before it is eligible for eviction by the idle object evictor (if any). Default is `1800000` (30 minutes).
* **`jdbc.pooling.remove-abandoned-timeout.millis`** (since 8.0.11): Timeout in milliseconds before an abandoned connection can be removed. Default is `300000` (5 minutes).
* **`jdbc.pooling.test-on-borrow`** (since 8.0.12): Whether or not the pool will validate objects before they are borrowed from the pool. Default is `false`. 

* **`smp.flyway.enabled`**: enable or disable the usage of Flyway. It is highly recommended to NOT use this configuration item except you got instructions to do so. Allowed values are `true` (=enabled) and `false` (disabled). The default value is `true`.
* **`smp.flyway.jdbc.url`** (since 7.0.4): Specific configuration for Flyway: The JDBC URL of the database to connect to. For a local MySQL database called "smp" the string would look like this: `jdbc:mysql://localhost:3306/smp?autoReconnect=true`.
  <br>If this property is not provided, the value of the property `jdbc.url` is used instead
* **`smp.flyway.jdbc.user`** (since 7.0.4): Specific configuration for Flyway: The database user to be used when connecting to the database.
  <br>If this property is not provided, the value of the property `jdbc.user` is used instead
* **`smp.flyway.jdbc.password`** (since 7.0.4): Specific configuration for Flyway: The password of the JDBC user to be used when connecting to the DB
  <br>If this property is not provided, the value of the property `jdbc.password` is used instead
* **`smp.flyway.jdbc.schema-create`** (since 8.1.4): Should Flyway try to create the database schema (value `true`) or not (value `false`). The default value is `false`.
  <br>This is the preferred key for schema creation configuration. If not set, the old key `jdbc.schema-create` is used as a fallback.
* **`smp.flyway.baseline.version`** (since 6.0.0): defines the baseline version to be used for Flyway. This is an advanced configuration property. Don't use it except instructed to do so.
* **`smp.flyway.history-table`** (since 8.1.4): The name of the Flyway history table. The default value is `flyway_schema_history`.
* **`smp.flyway.debug-mode`** (since 8.1.4): Enable or disable Flyway debug mode for more verbose logging. Allowed values are `true` and `false`. The default value is `false`.
* **`smp.flyway.repair-mode`** (since 8.1.4): Enable or disable Flyway repair mode. When enabled, Flyway runs a repair before each migration to fix failed migration entries. Allowed values are `true` and `false`. The default value is `false`.
  
### <a name="postgresql"></a> PostgreSQL Specific Configuration

For usage with the SMP you need to create a Database manually as well as a Login (matching the configuration items `jdbc.user` and `jdbc.password`) that needs the privilege "Can login" on that Database.
If the configuration `smp.flyway.jdbc.schema-create` (or the old key `jdbc.schema-create`) is set to `false` you also need to create the Schema (matching the configuration item `jdbc.schema`) inside the Database before you can start.

## <a name="xml"></a> XML Backend Specific Configuration

When the **XML** backend is used no further configuration properties are available. The XML data is stored in the directory denoted by the `webapp.datapath` property.

## <a name="mongodb"></a> MongoDB Backend Specific Configuration

When the **MongoDB** backend is used, the following properties are also available:

* **`mongodb.connectionstring`**: The connection string to be used. The most simple one is e.g. `mongodb://localhost`.
* **`mongodb.dbname`**: The database name to be used. The recommended value is `phoss-smp`.

# <a name="internalerror"></a> Internal Error Handling Configuration

An internal error handling can be configured, so that the SMP server tries to send an email in case an internal error occurs.
This works independent of the used backend and can be used with any of them equally.
Therefore the following configuration properties are available:

* **`smp.errorhandler.sender.email`**: the sender email address of the internal error email (e.g. `smp@example.org`)
* **`smp.errorhandler.sender.name`**: the sender display name of the internal error email. Defaults to `SMP Internal Error Sender`.
* **`smp.errorhandler.receiver.email`**: the receiver email address of the internal error email (e.g. `support@example.org`)
* **`smp.errorhandler.receiver.name`**: the receiver display name of the internal error email (e.g. `Example Support`)
* **`smp.smtp.hostname`**: SMTP hostname to use. Either as domain name or as IP address.
* **`smp.smtp.port`**: SMTP server port
* **`smp.smtp.username`**: optional SMTP user name
* **`smp.smtp.password`**: optional SMTP password
* **`smp.smtp.ssl`**: use SMTP SSL connection? Defaults to `false`
* **`smp.smtp.starttls`**: use SMTP STARTTLS connection? Defaults to `false`
* **`smp.smtp.connectiontimeoutms`**: SMTP server connection timeout in milliseconds. Defaults to `10000` (10 seconds).
* **`smp.smtp.sockettimeoutms`**: SMTP server read timeout in milliseconds. Defaults to `10000` (10 seconds).
* **`smp.smtp.debug`**: Emit debug SMTP server output? Defaults to `false`