Skip to content

Configuration

Philip Helger edited this page Jul 3, 2019 · 49 revisions

This page explains the configuration options for the SMP server. It ships with the following configuration files:

  • webapp.properties for user interface properties
  • smp-server.properties for SMP functionality properties
  • pd-client.properties for (PEPPOL|TOOP) Directory client configuration

All files reside by default in the src/main/resources folder of the peppol-smp-server-webapp project. All .properties files use ISO-8859-1 as their default encoding.

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!

Database configuration (SQL)

This project was tested with MySQL 5.x as a backend and it works without problems. The DDL to create the initial database can be found in the folder https://github.com/phax/peppol-smp-server/tree/master/peppol-smp-server-sql/database_backups

The file found there also creates the default DB user peppol_user with the password Test1234. It is strongly recommended to change the password of this user asap.

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

webapp.properties

This properties file defines just settings relevant for the web application but not the SMP itself. Modifications to this file have no relevant impact on the SMP functionality.

Within the same folder a file webapp-production.properties is contained which provides suggested settings for a production environment. Only the data path should be adopted.

Alternatively the absolute path of this configuration file can be specified by the environment variable SMP_WEBAPP_CONFIG (since v5.1.0) or alternatively by the system property peppol.smp.webapp.properties.path or smp.webapp.properties.path (in that order).

It contains the following 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 (since 5.0.7): 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.
  • 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.
  • 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 (only in 4.0.3): the version number indicating the SMP server software version number
  • webapp.startpage.dynamictable (since 5.0.2): 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 (since 5.0.4): 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 (since 5.1.0): true to show the content of the extensions in the public list of contained service groups. Default is false.
  • webapp.directory.name (since 5.0.7): 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 (since 5.1.0): true to show the content of the extensions in the service group list in the administrative area. Default is false.
  • webapp.public.login.enabled (since 5.2.0): true to show a login UI element on the /public part, false to not show it. The default value is true.

smp-server.properties

The SMP service is configured using a single configuration file src/main/resources/smp-server.properties. Alternatively the absolute path of the SMP configuration file can be specified by the environment variable SMP_SERVER_CONFIG (since v5.1.0) or alternatively by the system property peppol.smp.server.properties.path or smp.server.properties.path (in that order).

The following list describes all the possible configuration items:

  • smp.backend: The backend to be used. Can either be "sql" or "xml". Any other value will result in a startup error.
  • smp.keystore.type (since 5.0.4): The type of the keystore. Can either be JKS or PKCS12. The value is case insensitive. The default value is JKS.
  • smp.keystore.path: The classpath - relative to the project - where the Java key store (of type JKS) 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 JKS keystore is located.
    Note: The key store should contain exactly one certificate entry with an arbitrary name and the certificate must have the same password as the whole key store!
  • smp.keystore.password: The password used to access the key store.
  • smp.keystore.key.alias: The alias of the key within the key store. Is case sensitive and may not be empty. This 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.path (since 5.0.0): The classpath - relative to the project - where the Java trust store (of type JKS) with the public certificates of the SMLs to communicate with are contained. This property is optional. If no trust store path is provided, the SML client caller trusts all SML https certificates.
  • smp.truststore.password (since 5.0.0): The password used to access the truststore. 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 Apache httpd.
  • smp.publicurl (since 4.1.0): 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) to pass out the correct name in SMP responses that require absolute URLs.
  • smp.identifiertype (since 5.0.0): 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
    • bdxr - the BDXR SMP identifier rules are applied
  • smp.rest.type (since 5.0.0): 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 specification (XML namespace URI http://docs.oasis-open.org/bdxr/ns/SMP/2016/05)
  • smp.rest.log.exceptions (since 5.1.0): this property enables or disables the detailed logging of exceptions that occur while processing REST calls. By default the logging is disabled.
  • smp.status.enabled (since 5.0.6): this property can be used to enable or disable the status API at /smp-status/. By default the status API is enabled.
  • 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 (since 5.0.3): 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.active is set to true.
  • sml.smp.hostname (since 5.0.3): 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.active is set to true.
  • sml.connection.timeout.ms (since 5.0.4): if this property is present it sets the connection timeout in milliseconds to the configured SML.
    Note: is only required if the entry sml.active is set to true.
  • sml.request.timeout.ms (since 5.0.4): if this property is present it sets the request timeout in milliseconds to the configured SML.
    Note: is only required if the entry sml.active is set to true.

GUI managable

Since version v5.0.2 the following properties can be managed on the GUI and therefore the effective values used, may differ from the ones specified in the configuration file:

  • 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 adds, updates or deletes of participants is communicated to the SML which will create the respective DNS entries.
  • sml.needed (since 5.0.4): This fields 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.url (up to and including 5.0.6): The URL of the SML manage business identifier service. For production purposes (SML) use https://edelivery.tech.ec.europa.eu/edelivery-sml/manageparticipantidentifier. For the test-SML (SMK) use the URL https://acc.edelivery.tech.ec.europa.eu/edelivery-sml/manageparticipantidentifier.
    Note: is only required if the entry sml.active is set to true.
    Note: from v5.0.7 the way how to select SML configurations changed and this flag is obsoleted
  • 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).
  • smp.peppol.directory.integration.enabled (since 4.1.2): set this property to true to activate the PEPPOL Directory Business Card Features
  • smp.peppol.directory.hostname (since 4.1.2): the fully qualified host name of the PEPPOL Directory server. Defaults to https://directory.peppol.eu.
    Note: up to and including version 5.0.2 the default value was http://pyp.helger.com
  • smp.peppol.directory.integration.autoupdate (since 5.0.4): automatically update the PEPPOL Directory server, if something changes in the business card. This feature can be changed on the UI of the SMP.

HTTP proxy settings

The following settings are only needed, when running the SMP behind a proxy server. They are available since version v5.0.7:

  • 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 PEPPOL Directory is used, ensure that your pd-client.properties file also contains the respective HTTP proxy configuration items as outlined in https://github.com/phax/phoss-directory/#pd-client

SQL backend specific

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
  • target-database: The JPA target database type to be used. For MySQL this value should be MySQL
    Note: Please see the documentation of EclipseLink for other target database systems!
  • jdbc.read-connections.max: The maximum number of JDBC connections to be used for reading. Usually 10 should be suitable for most use cases.
  • jdbc.execution-time-warning.enabled (since 5.0.6): 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 (since 5.0.6): 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).

XML backend specific

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 in the webapp.properties file.

MongoDB backend specific

When the MongoDB backend is used (since v5.2.0), 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 configuration

Since version 5 you can configure internal error handling so that the SMP server tries to send an email in case an internal error occurs. 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

Example files - XML backend

Example of a development smp-server.properties file with XML backend (for easy testing):

# The backend to be used
smp.backend = xml

## Keystore data
smp.keystore.path         = keystore/keystore.jks
smp.keystore.password     = peppol
smp.keystore.key.alias    = smp keypair
smp.keystore.key.password = peppol

# Force all paths to be "/" instead of the context path 
smp.forceroot = true

## Write to SML? true or false
sml.active=false

Example of a production-like smp-server.properties with XML backend (for close to production setup):

# The backend to be used
smp.backend = xml

## Keystore data
smp.keystore.path         = keystore/keystore.jks
smp.keystore.password     = peppol
smp.keystore.key.alias    = smp keypair
smp.keystore.key.password = peppol

# Force all paths to be "/" instead of the context path 
smp.forceroot = true

## Write to SML? true or false
sml.active=true
# SMP ID
sml.smpid=TEST-SMP-ID1
# SML URL (incl. the service name)
sml.url=https://edelivery.tech.ec.europa.eu/edelivery-sml/manageparticipantidentifier

Example files - SQL backend

Example of a development smp-server.properties file using a local MySQL database called smp without an SML connector (for easy testing):

# The backend to be used
smp.backend = sql

## Keystore data
smp.keystore.path         = keystore/keystore.jks
smp.keystore.password     = peppol
smp.keystore.key.alias    = smp keypair
smp.keystore.key.password = peppol

# Force all paths to be "/" instead of the context path 
smp.forceroot = true

## Write to SML? true or false
sml.active=false

## JDBC configuration for DB
jdbc.driver = com.mysql.jdbc.Driver
jdbc.url = jdbc:mysql://localhost:3306/smp
jdbc.user = smp
jdbc.password = smp
target-database = MySQL
jdbc.read-connections.max = 10

## Warn if JDBC execution time is exceeded? (since 5.0.6)
jdbc.execution-time-warning.enabled = true
jdbc.execution-time-warning.ms = 5000

Example of a production-like smp-server.properties file using a local MySQL database called smp with the SML connector (for close to production setup):

# The backend to be used
smp.backend = sql

## Keystore data
smp.keystore.path         = keystore/keystore.jks
smp.keystore.password     = peppol
smp.keystore.key.alias    = smp keypair
smp.keystore.key.password = peppol

# Force all paths to be "/" instead of the context path 
smp.forceroot = true

## Write to SML? true or false
sml.active=true
# SMP ID
sml.smpid=TEST-SMP-ID1
# SML URL (incl. the service name)
sml.url=https://edelivery.tech.ec.europa.eu/edelivery-sml/manageparticipantidentifier

## JDBC configuration for DB
jdbc.driver = com.mysql.jdbc.Driver
jdbc.url = jdbc:mysql://localhost:3306/smp
jdbc.user = smp
jdbc.password = smp
target-database = MySQL
jdbc.read-connections.max = 10

pd-client.properties

The PEPPOL Directory (PD)/TOOP Directory client, that can optionally be used inside the SMP also requires a configuration file called pd-client.properties (PEPPOL Directory Client properties). The resolution rules are:

  1. Check for the value of the system property peppol.pd.client.properties.path
  2. Check for the value of the system property pd.client.properties.path
  3. The filename private-pd-client.properties in the root of the classpath
  4. The filename pd-client.properties in the root of the classpath

The following list describes the relevant configuration items:

  • keystore.type: The type of the keystore. Can either be JKS or PKCS12. The value is case insensitive. The default value is JKS.
    Note: This value corresponds to the value of smp.keystore.type in smp-server.properties
  • keystore.path: The classpath - relative to the project - where the Java key store (of type JKS) 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 JKS keystore is located.
    Note: The key store should contain exactly one certificate entry with an arbitrary name and the certificate must have the same password as the whole key store!
    Note: This value corresponds to the value of smp.keystore.path in smp-server.properties
  • keystore.password: The password used to access the key store.
    Note: This value corresponds to the value of smp.keystore.password in smp-server.properties
  • keystore.key.alias: The alias of the key within the key store. Is case sensitive and may not be empty. This alias is used to sign certain response messages.
    Note: This value corresponds to the value of smp.keystore.key.alias in smp-server.properties
  • 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 keystore.password).
    Note: This value corresponds to the value of smp.keystore.key.password in smp-server.properties

See https://github.com/phax/phoss-directory/#pd-client for further details on the HTTP proxy configuration etc.

You can’t perform that action at this time.