Skip to content

Configuration Properties

Jump to bottom
Philip Helger edited this page Mar 11, 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.
  • peppol.identifier.mode: The Peppol identifier validation mode. Either strict or lax. In strict mode (default), all Peppol identifier rules are enforced. In lax mode, identifier validation is more lenient. Default is strict.

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 configuration properties are defined by JdbcConfigurationConfig from ph-db. All properties use the prefix phossap.jdbc..

  • phossap.jdbc.database-type: The target database type. Must be PostgreSQL.
  • phossap.jdbc.driver: The JDBC driver class. For PostgreSQL use org.postgresql.Driver.
  • phossap.jdbc.url: The JDBC URL of the database. Example: jdbc:postgresql://localhost:5432/phossap.
  • phossap.jdbc.user: The database user.
  • phossap.jdbc.password: The password of the database user.
  • phossap.jdbc.schema: The database schema to use. Default is public.
  • phossap.jdbc.execution-time-warning.enabled: Enable or disable logging of long-running JDBC transactions. Default is true.
  • phossap.jdbc.execution-time-warning.ms: Threshold in milliseconds for the long-running JDBC transaction warning. Default is 1000.
  • phossap.jdbc.debug.connections: Enable or disable debug logging of JDBC connection lifecycle (open/close). Default is false.
  • phossap.jdbc.debug.transactions: Enable or disable debug logging of JDBC transactions (begin/commit/rollback). Default is false.
  • phossap.jdbc.debug.sql: Enable or disable debug logging of executed SQL statements. Default is false.

Connection Pooling

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

Flyway

Configuration properties for Flyway database migrations, as defined by FlywayConfigurationBuilderConfig from ph-db. All properties use the prefix flyway. and fall back to the main JDBC properties if not explicitly set.

  • phossap.flyway.enabled: Enable or disable Flyway database migrations on startup. Default is true.
  • phossap.flyway.jdbc.url: Optional separate JDBC URL for Flyway migrations. Falls back to phossap.jdbc.url if not set.
  • phossap.flyway.jdbc.user: Optional separate database user for Flyway. Falls back to phossap.jdbc.user if not set.
  • phossap.flyway.jdbc.password: Optional separate database password for Flyway. Falls back to phossap.jdbc.password if not set.
  • phossap.flyway.jdbc.schema-create: Whether Flyway should attempt to create the database schema. Default is false.
  • phossap.flyway.baseline.version: The Flyway baseline version (integer). Used when baselining an existing database. Default is 0.

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.

Document Storage

Document payloads (SBD files) are stored as flat files on disk rather than in the database. The following properties configure the base directories for inbound and outbound document files.

  • storage.inbound.path: Absolute path to the directory where inbound document files are stored. Default is /var/phoss-ap/inbound. The directory is created automatically if it does not exist.
  • storage.outbound.path: Absolute path to the directory where outbound document files are stored. Default is /var/phoss-ap/outbound. The directory is created automatically if it does not exist.

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: (Required) Selects the active forwarding implementation. One of: http_post_sync, http_post_async, s3_link, sftp. Must be explicitly configured — there is no default.

HTTP POST Forwarding

  • forwarding.http.endpoint: The URL of the Receiver Backend endpoint to POST the SBD to.

The HTTP client used for forwarding is configured via HttpClientSettingsConfig from ph-web with the prefix forwarding.. All properties below are optional and have sensible defaults.

Timeouts

  • forwarding.http.timeout.connect.millis (or .seconds, .minutes, .hours): Connect timeout for the HTTP POST.
  • forwarding.http.timeout.response.millis (or .seconds, .minutes, .hours): Response/read timeout for the HTTP POST.
  • forwarding.http.timeout.connectionrequest.millis (or .seconds, .minutes, .hours): Timeout for obtaining a connection from the pool.

Retry

  • forwarding.http.retry.count: Number of HTTP-level retries (integer, >= 0). Not set by default.
  • forwarding.http.retry.interval.millis (or .seconds, .minutes, .hours): Interval between HTTP-level retries.
  • forwarding.http.retry.always: Whether to retry on all failures (boolean). Default is the HttpClient default.

Proxy

  • forwarding.http.proxy.enabled: Enable a separate HTTP proxy for forwarding requests. Default is false.
  • forwarding.http.proxy.host: Proxy hostname.
  • forwarding.http.proxy.port: Proxy port (integer).
  • forwarding.http.proxy.username: Proxy authentication username.
  • forwarding.http.proxy.password: Proxy authentication password.
  • forwarding.http.proxy.nonProxyHosts: Pipe-separated list of hosts that bypass the proxy.

TLS

  • forwarding.http.tls.checks.disabled: Disable all TLS checks (hostname + certificate). Default is false. Security risk — use only for testing.
  • forwarding.http.tls.hostname-check.disabled: Disable TLS hostname verification only. Default is false.
  • forwarding.http.tls.certificate-check.disabled: Disable TLS certificate verification only. Default is false.

Miscellaneous

  • forwarding.http.useragent: Custom User-Agent header for forwarding requests.
  • forwarding.http.follow-redirects: Whether to follow HTTP redirects. Default is the HttpClient default.
  • forwarding.http.keep-alive: Whether to use HTTP keep-alive connections. Default is the HttpClient default.
  • forwarding.http.dnsclientcache.use: Whether to use the DNS client cache.
  • forwarding.http.protocol-upgrade.enabled: Enable HTTP/2 protocol upgrade. Default is the HttpClient default.

S3 Forwarding

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

SFTP Forwarding

  • 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.connectiontimeoutms: Connection timeout in milliseconds. Default is defined by ISftpSettingsHost.DEFAULT_CONNECTION_TIMEOUT_MS.
  • forwarding.sftp.user: The username for SFTP authentication.
  • forwarding.sftp.password: The password for SFTP authentication. Either this or a key pair must be provided.
  • forwarding.sftp.keypair.privatekeypath: Path to the private key file for key-based authentication.
  • forwarding.sftp.keypair.publickeypath: Path to the public key file for key-based authentication.
  • forwarding.sftp.keypair.passphrase: Optional passphrase for the key pair.
  • forwarding.sftp.knownhostspath: Path to the SSH known_hosts file for host key verification. Optional — if not set, host key checking may be skipped.
  • forwarding.sftp.maxconnections: Maximum number of parallel SFTP connections. Default is defined by ISftpSettingsHost.DEFAULT_MAX_CONNECTIONS.
  • forwarding.sftp.directory: The remote directory on the SFTP server where SBDs are uploaded.

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). Safe to enable on all instances — uses SKIP LOCKED for work distribution.

Circuit Breaker

Per-C3 circuit breaker for outbound AS4 sending. Implemented in-memory using Failsafe. See Retry and Resilience Patterns for details.

  • circuit-breaker.failure-threshold: Number of consecutive failures to a C3 endpoint before the circuit breaker opens. Default is 5.
  • circuit-breaker.open-duration.ms: Duration in milliseconds the circuit breaker stays open before transitioning to half-open. Default is 60000 (1 minute).
  • circuit-breaker.half-open-max-attempts: Number of probe attempts allowed through in half-open state to test if the C3 endpoint has recovered. Default is 1.

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.schedule.enabled: Enable or disable the reporting schedule. 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 6.
  • peppol.reporting.schedule.minute: Minute of the hour at which reporting is submitted (0-59). Default is 7.

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.

Archival Configuration

  • archival.scheduler.enabled: Enable or disable the periodic archival scheduler. Default is true. Safe to enable on all instances — uses SKIP LOCKED for work distribution.
  • archival.scheduler.interval.ms: Interval in milliseconds at which the archival scheduler runs. Default is 3600000 (1 hour).

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

Shutdown and Startup Recovery

  • shutdown.timeout.ms: Maximum time in milliseconds to wait for in-flight sending and forwarding operations to complete during graceful shutdown. After this timeout, remaining tasks are interrupted. Default is 30000 (30 seconds).
  • startup.recovery.enabled: Enable or disable stale transaction recovery at startup. When true, transactions left in transient states (sending, forwarding) from a previous unclean shutdown are reset to their retry-eligible states (failed, forward_failed) with next_retry_dt = NOW(). Default is true.

See also the Spring Boot properties server.shutdown and spring.lifecycle.timeout-per-shutdown-phase in the Spring Boot / Server Configuration section.

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

Sentry Error Tracking

Optional integration with Sentry for real-time error tracking and alerting. Sentry is fully disabled by default and activates only when the sentry.dsn property is set and the sentry-logback dependency is on the classpath.

When active, a Logback SentryAppender is registered automatically. Additionally, a SentryNotificationHandler is registered that reports business-level failure events (e.g. sending failures, forwarding failures, verification rejections, reporting failures) to Sentry with structured attributes.

  • sentry.dsn: The Sentry Data Source Name (DSN) for your project (e.g. https://<key>@sentry.io/<project>). If not set, Sentry is fully disabled. Treat as a secret — place it in application-private.properties or inject via environment variable.
  • sentry.send-default-pii: Enable sending of Personally Identifiable Information such as request headers and IP addresses. See the Sentry PII documentation for details. Default is true.
  • sentry.logging.minimum-event-level: The minimum Logback level at which log events are sent to Sentry as events. Default is ERROR.
  • sentry.logging.minimum-breadcrumb-level: The minimum Logback level at which log events are captured as Sentry breadcrumbs. Default is INFO.

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.shutdown: Shutdown mode. Set to graceful to enable graceful shutdown (stop accepting new requests, drain in-flight requests). Default is immediate.
  • spring.lifecycle.timeout-per-shutdown-phase: Maximum time Spring Boot waits for the servlet container to drain in-flight HTTP requests during graceful shutdown. Example: 30s. Default is 30s.
  • 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