Skip to content

Configuration

Jump to bottom
Philip Helger edited this page Apr 24, 2024 · 103 revisions

This page explains the configuration options for the SMP server version 6.x. If you need information for phoss SMP version 5.x please see the legacy page Configuration V5.

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)

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 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: The MySQL database should be 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.

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.

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.version: the version number indicating the SMP server software version number
  • 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.startpage.dynamictable: make the public start page a dynamic page with searching, paging etc. This is slower than the static version because additional requests need to be performed. This property is mainly present to restore the default behaviour for versions up to 5.0.1. The default value is false.
  • webapp.startpage.participants.none: set this property to true to disable the listing of all maintained participants of the SMP on the public start page. The default value is false.
  • webapp.startpage.extensions.show: true to show the content of the extensions in the public list of contained service groups. Default is false.
  • 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. The default value is true for backwards compatibility reasons.
  • webapp.public.login.enabled: true to show a login UI element on the /public application part, false to not show it. The default value is true.
  • 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 6.0.0): an optional data URL that contains an image that will be used as the application logo.
  • webapp.logo.externalurl (since 6.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 6.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 4 can be used. Example value: mx-3 badge badge-primary.
  • webapp.page.admin.monitoring.sessions.disabled (since 6.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 6.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 6.0.1): enables or disables the usage of Markdown (MD) for system messages. By default is is true.
  • 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.

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.
    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.
    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
    • dynamic-participant - will use the dynamically created hostname (Note: this may be slow when used with BDXR mode, because this will perform a NAPTR resolution)
  • 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
  • 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.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.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.
    Note: it must be the same ID that was used for the initial registration of the SMP to the SML.
    Note: is only required if the entry sml.active 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.
    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.
    Note: has only effect if the entry sml.enabled is set to true.
  • sml.connection.timeout.ms: if this property is present it sets the connect timeout in milliseconds to the configured SML.
    Note: is only required if the entry sml.enabled is set to true.
  • sml.request.timeout.ms: if this property is present it sets the response timeout in milliseconds to the configured SML.
    Note: is only required if the entry sml.enabled is set to true.

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.active 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.

Directory Client Configuration

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

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

Type of Backend Specific Configuration

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
    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: Should Flyway try to create the database schema (value true) or not (value false). The default value is false.
  • target-database: The target database type to be used.
    For MySQL this should be MySQL.
    For PostgreSQL this should be PostgreSQL
    For Oracle this should be Oracle
    For DB2 this should be DB2
    Note: this is not the name of the database schema. That name is part of the jdbc.url.
  • 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.ms: the milliseconds after which a warning will be emitted if a JDBC transaction takes longer. This only has an effect if the configuration item jdbc.execution-time-warning.enabled evaluates to true. The default value is 1000 (1 second).
  • 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.
    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.
    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
    If this property is not provided, the value of the property jdbc.password is used instead
  • 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.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.

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 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.

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.

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.

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

On Twitter: Follow @philiphelger

Donation link: https://paypal.me/PhilipHelger

It is appreciated if you star the GitHub project if you like it.

Logo

Clone this wiki locally