Skip to content

Configuration Properties

Jump to bottom
Philip Helger edited this page Feb 24, 2026 · 49 revisions

Configuration Properties

All properties are located in the file application.properties which resides in src/main/resources of the phoss-ap-webapp module.

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

Table of Contents

General Configuration

  • global.debug: Enable or disable overall debug mode. Enables additional checks that should not be active in production (e.g. verbose logging, slower validation). Default is false.
  • global.production: Enable or disable overall production mode. When false, certain production-only functionality may be disabled. Default is false.
  • global.nostartupinfo: Set to true to suppress the startup information banner. Default is false.
  • global.datapath: The path where all relevant data files are stored (e.g. keystores, dumps, logs). Should be an absolute path in production (e.g. /var/phoss-ap/data).

Peppol Configuration

  • peppol.stage: The Peppol network stage. Either test or prod. Determines which PKI certificates and SML endpoints are used.
  • peppol.seatid: The Peppol Seat ID of this AP (e.g. POP000000). Used in reporting and MLS processing.
  • peppol.owner.countrycode: The 2-letter country code of the AP operator. Used as C2 or C3 country in reporting context.

AS4 Keystore and Truststore

These properties configure the cryptographic material used by phase4 for AS4 message signing, encryption, and certificate validation.

AP Keystore (signing and decryption)

  • org.apache.wss4j.crypto.merlin.keystore.type: Keystore type. Either JKS or PKCS12. Default is JKS.
  • org.apache.wss4j.crypto.merlin.keystore.file: Path to the keystore file containing the AP certificate and private key.
  • org.apache.wss4j.crypto.merlin.keystore.password: Password for the keystore.
  • org.apache.wss4j.crypto.merlin.keystore.alias: Alias of the key entry within the keystore.
  • org.apache.wss4j.crypto.merlin.keystore.private.password: Password for the private key entry.

AP Truststore (validating remote AP certificates)

  • org.apache.wss4j.crypto.merlin.truststore.type: Truststore type. Either JKS or PKCS12. Default is PKCS12.
  • org.apache.wss4j.crypto.merlin.truststore.file: Path to the truststore file for validating incoming AS4 message signatures.
  • org.apache.wss4j.crypto.merlin.truststore.password: Password for the truststore.

SMP Client Configuration

These properties configure the SMP client used for outbound SMP lookups (to resolve receiver AP endpoints).

  • smpclient.truststore.type: Truststore type for SMP client TLS connections. Either JKS or PKCS12. Default is PKCS12.
  • smpclient.truststore.path: Path to the truststore file for SMP client connections.
  • smpclient.truststore.password: Password for the SMP client truststore.

Database Configuration

PostgreSQL is the required database. The database schema is managed automatically via Flyway.

  • jdbc.driver: The JDBC driver class. For PostgreSQL use org.postgresql.Driver.
  • jdbc.url: The JDBC URL of the database. Example: jdbc:postgresql://localhost:5432/phossap.
  • jdbc.user: The database user.
  • jdbc.password: The password of the database user.
  • jdbc.schema: The database schema to use. Default is public.
  • jdbc.schema-create: Whether Flyway should attempt to create the database schema (true or false). Default is false.
  • target-database: The target database type. Must be PostgreSQL.
  • jdbc.execution-time-warning.enabled: Enable or disable logging of long-running JDBC transactions. Default is true.
  • jdbc.execution-time-warning.ms: Threshold in milliseconds for the long-running JDBC transaction warning. Default is 1000.

Connection Pooling

  • jdbc.pooling.max-connections: Maximum number of active connections in the pool. Default is 8.
  • jdbc.pooling.max-wait.millis: Maximum milliseconds to wait for a connection from the pool before throwing an exception. Default is 10000.
  • jdbc.pooling.between-evictions-runs.millis: Milliseconds between runs of the idle connection evictor. Default is 300000.
  • jdbc.pooling.min-evictable-idle.millis: Minimum idle time in milliseconds before a connection is eligible for eviction. Default is 1800000.
  • jdbc.pooling.remove-abandoned-timeout.millis: Timeout in milliseconds before an abandoned connection can be removed. Default is 300000.

Flyway

  • flyway.jdbc.url: Optional separate JDBC URL for Flyway migrations. Falls back to jdbc.url if not set.
  • flyway.jdbc.user: Optional separate database user for Flyway. Falls back to jdbc.user if not set.
  • flyway.jdbc.password: Optional separate database password for Flyway. Falls back to jdbc.password if not set.

API Configuration

  • phase4.endpoint.address: The public AS4 endpoint URL of this AP (e.g. https://ap.example.com/as4). Used by phase4 for endpoint comparison and in reporting.
  • phase4.api.requiredtoken: The API token required for authenticating REST API calls (sent via X-Token header). If empty or not set, API authentication is disabled.

Sending Configuration

  • peppol.sending.enabled: Enable or disable outbound AS4 sending. Set to false to operate as a receive-only AP. Default is true.

Receiving Configuration

  • peppol.receiving.enabled: Enable or disable inbound AS4 receiving. Set to false to operate as a send-only AP. Default is true.

Forwarding Configuration

  • forwarding.mode: The forwarding mode to use for delivering received documents to the Receiver Backend. One of: http_post_async, http_post_sync, s3_link, sftp. This is configured per AP instance — exactly one mode per deployment.

HTTP POST Forwarding

Applicable when forwarding.mode is http_post_async or http_post_sync.

  • forwarding.http.endpoint: The URL of the Receiver Backend endpoint to POST the SBD to.
  • forwarding.http.connection-timeout.ms: Connection timeout in milliseconds for the HTTP POST. Default is 5000.
  • forwarding.http.response-timeout.ms: Response timeout in milliseconds for the HTTP POST. Default is 30000.

S3 Forwarding

Applicable when forwarding.mode is s3_link.

  • forwarding.s3.bucket: The S3 bucket name where received SBDs are stored.
  • forwarding.s3.region: The AWS region of the S3 bucket (e.g. eu-central-1).
  • forwarding.s3.access-key-id: AWS access key ID for S3 access. Optional if using IAM roles.
  • forwarding.s3.secret-access-key: AWS secret access key for S3 access. Optional if using IAM roles.
  • forwarding.s3.key-prefix: Optional prefix (folder path) for S3 object keys.
  • forwarding.s3.link.endpoint: The URL of the Receiver Backend endpoint to notify with the S3 reference.

SFTP Forwarding

Applicable when forwarding.mode is sftp.

  • forwarding.sftp.host: The hostname or IP address of the SFTP server.
  • forwarding.sftp.port: The port of the SFTP server. Default is 22.
  • forwarding.sftp.username: The username for SFTP authentication.
  • forwarding.sftp.password: The password for SFTP authentication. Either this or a private key must be provided.
  • forwarding.sftp.private-key-path: Path to the private key file for SFTP key-based authentication.
  • forwarding.sftp.private-key-passphrase: Optional passphrase for the private key.
  • forwarding.sftp.directory: The remote directory on the SFTP server where SBDs are uploaded.
  • forwarding.sftp.known-hosts-path: Path to the SSH known_hosts file for host key verification.

Retry Configuration

Retry behavior is defined via customizable Java interfaces. The following properties configure the default retry strategy.

  • retry.sending.max-attempts: Maximum number of AS4 sending attempts for outbound transactions before marking as permanently failed. Default is 3.
  • retry.sending.initial-backoff.ms: Initial backoff interval in milliseconds between sending retries. Default is 60000 (1 minute).
  • retry.sending.backoff-multiplier: Multiplier applied to the backoff interval after each failed attempt (exponential backoff). Default is 2.0.
  • retry.sending.max-backoff.ms: Maximum backoff interval in milliseconds. Default is 3600000 (1 hour).
  • retry.forwarding.max-attempts: Maximum number of forwarding attempts for inbound transactions before marking as permanently failed. Default is 3.
  • retry.forwarding.initial-backoff.ms: Initial backoff interval in milliseconds between forwarding retries. Default is 60000 (1 minute).
  • retry.forwarding.backoff-multiplier: Multiplier applied to the backoff interval after each failed forwarding attempt. Default is 2.0.
  • retry.forwarding.max-backoff.ms: Maximum backoff interval in milliseconds for forwarding retries. Default is 3600000 (1 hour).
  • retry.scheduler.interval.ms: Interval in milliseconds at which the retry scheduler checks for transactions eligible for retry. Default is 60000 (1 minute).

Verification Configuration

  • verification.outbound.enabled: Enable or disable optional verification of outbound documents before AS4 sending. Default is false.
  • verification.inbound.enabled: Enable or disable optional verification of inbound documents before forwarding. Default is false.

The actual verification logic is provided via the pluggable IDocumentVerifier SPI. These properties only control whether the verification step is invoked.

MLS Configuration

  • mls.type: The MLS sending strategy for this AP instance (as C3). Either FAILURE_ONLY or ALWAYS_SEND. Default is ALWAYS_SEND. This value is captured per inbound transaction at reception time.

Reporting Configuration

  • peppol.reporting.senderid: The Peppol Participant ID used as the sender of Peppol Reporting messages (TSR/EUSR).
  • peppol.reporting.scheduled: Enable or disable scheduled automatic Peppol Reporting submission. Default is true.
  • peppol.reporting.schedule.day-of-month: Day of the month on which reporting is submitted (1-31). Default is 2.
  • peppol.reporting.schedule.hour: Hour of the day at which reporting is submitted (0-23). Default is 5.
  • peppol.reporting.schedule.minute: Minute of the hour at which reporting is submitted (0-59). Default is 0.

Duplicate Detection Configuration

  • duplicate.detection.as4.mode: Behavior when an AS4 Message ID duplicate is detected. Either reject or store_and_flag. Default is reject.
  • duplicate.detection.sbdh.mode: Behavior when an SBDH Instance Identifier duplicate is detected. Either reject or store_and_flag. Default is reject.
  • duplicate.detection.business.mode: Behavior when a Business Document ID duplicate is detected. Either reject or store_and_flag. Default is store_and_flag.

Archival Configuration

  • archival.scheduler.enabled: Enable or disable the periodic archival scheduler. Default is true.
  • archival.scheduler.interval.ms: Interval in milliseconds at which the archival scheduler runs. Default is 3600000 (1 hour).

Notification Configuration

Notification dispatch is handled via a generic Java interface (INotificationHandler). The following properties configure the default implementation.

  • notification.enabled: Enable or disable failure notifications. Default is true.

HTTP Proxy Configuration

These settings are needed when the AP runs behind an outbound proxy server. They affect AS4 sending, SMP lookups, CRL downloads, and reporting submission.

  • http.proxy.enabled: Enable or disable the use of an outbound HTTP proxy. Default is false.
  • http.proxy.host: Proxy host name or IP address.
  • http.proxy.port: Proxy port number.
  • http.proxy.username: Optional username for proxy authentication.
  • http.proxy.password: Optional password for proxy authentication.
  • http.proxy.nonProxyHosts: Pipe-separated list of hosts that should bypass the proxy (e.g. localhost|127.0.0.1).

Logging and Diagnostics

  • phase4.dump.path: Directory path where AS4 message dumps (request/response) are stored for debugging purposes. If not set, no dumps are created. Example: /var/phoss-ap/data/phase4-dumps/.

Spring Boot / Server Configuration

Standard Spring Boot properties for configuring the embedded server.

  • server.port: The HTTP port on which the AP listens. Default is 8080.
  • server.forward-headers-strategy: Strategy for handling forwarded headers when running behind a reverse proxy. Set to native when behind a proxy.
  • spring.servlet.multipart.max-file-size: Maximum file size for multipart uploads (document submission). Example: 100MB.
  • spring.servlet.multipart.max-request-size: Maximum request size for multipart uploads. Example: 100MB.

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

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

Clone this wiki locally