General Configuration#
BaSyx Go components use a shared application configuration model. Configuration can be provided through a YAML file and overridden with environment variables. This reference describes the common configuration shared by the component services.
Configuration Source Precedence#
The shared configuration loader applies the following precedence:
Environment variables
YAML configuration file
Built-in defaults
Environment variables override YAML values. Nested keys use underscore notation, for example server.port becomes SERVER_PORT.
Application Configuration: Core and Database#
These sections are part of the shared configuration model. Components consume only settings relevant to their feature set, but the shared loader still parses and validates configured values.
The defaults below are built into the shared configuration loader. A component’s bundled config.yaml can override them.
logging#
Key |
Default |
Purpose |
|---|---|---|
|
|
Log output format: |
|
|
Minimum log severity: |
All diagnostic logs are written to standard error. See
Observability for request logging, correlation IDs,
OpenTelemetry tracing and metrics, and log collection. OpenTelemetry settings
are standard OTEL_* environment variables rather than keys in this YAML
configuration model.
server#
Key |
Default |
Purpose |
|---|---|---|
|
|
Host used for the HTTP server and generated Swagger server URL. |
|
|
HTTP server port. |
|
|
Base path for API, Swagger, and health endpoints. |
|
|
Reserved switch. It does not currently enable runtime caching. |
|
|
Semantic verification mode: |
|
|
Enables the |
|
|
Maximum time in seconds to read HTTP request headers. |
|
|
Maximum time in seconds to read an entire HTTP request, including its body. |
|
|
Maximum time in seconds to write an HTTP response. |
|
|
Maximum time in seconds to wait for the next request on an idle keep-alive connection. |
|
|
Maximum time in seconds to wait for in-flight requests during graceful shutdown. |
|
|
Page size used when a request omits the |
|
|
Largest accepted |
|
|
Require |
All HTTP timeout values must be greater than 0. When a service receives an interrupt or termination signal, it stops accepting new connections and allows in-flight requests to finish for up to shutdownTimeoutSeconds.
The pagination limits apply to every paginated endpoint of every BaSyx Go service, including the REST Event Feed (GET /events). A request without limit returns at most pagination.defaultLimit items; the response carries a cursor when more items exist. A limit above pagination.maxLimit is rejected, not clamped, so clients never receive a shorter page than they asked for. Both values must be greater than 0, maxLimit must not be smaller than defaultLimit, and maxLimit must not exceed 2147483646. Lower maxLimit to bound the memory a single request can use on large datasets.
postgres#
Key |
Default |
Purpose |
|---|---|---|
|
|
Complete PostgreSQL connection string. It is mutually exclusive with the individual connection fields listed below; mixing both forms causes startup to fail. |
|
|
PostgreSQL host. |
|
|
PostgreSQL port. |
|
|
Database user. |
|
|
Database password. |
|
|
Database name. |
|
|
PostgreSQL TLS verification mode: |
|
|
Path to the client certificate used for certificate-based PostgreSQL authentication. |
|
|
Path to the private key belonging to |
|
|
Path to the root CA certificate used to verify the PostgreSQL server certificate. |
|
|
Connection timeout in seconds. Must not be negative; |
|
|
PostgreSQL |
|
|
Fallback application name used when no primary application name is supplied. |
|
|
PostgreSQL schema search path for new sessions. |
|
|
Additional PostgreSQL server startup options. |
|
|
PostgreSQL session time zone. |
|
|
Maximum number of open DB connections per service process or pod. |
|
|
Maximum number of idle DB connections per service process or pod. |
|
|
Maximum DB connection lifetime in minutes. |
|
|
Maximum time an idle connection is retained, in minutes. |
When postgres.dsn is non-empty, do not explicitly configure host, port, user, password, dbname, TLS, timeout, application-name, search-path, options, or time-zone fields in YAML or environment variables. The service rejects this ambiguous combination. Connection-pool settings can still be used with a DSN.
If no primary application_name is supplied through applicationName or the DSN, the component sets it to its service name. An explicitly configured value is preserved. This identifies each BaSyx service in PostgreSQL views such as pg_stat_activity.
Optional PostgreSQL reader#
Note
The BaSyx Read Replica Example runs the combined AAS Environment with a PostgreSQL primary and a real streaming standby. It includes checks for replication and writer/reader connection routing.
PostgreSQL-backed BaSyx HTTP services can use a separate reader connection for
eligible, eventually consistent reads. Configure it as a nested
postgres.reader block:
postgres:
host: postgres-primary
port: 5432
user: basyx
password: change-me
dbname: basyx
sslmode: verify-full
sslrootcert: /run/secrets/postgres/ca.crt
maxOpenConnections: 30
maxIdleConnections: 15
connMaxLifetimeMinutes: 5
connMaxIdleTimeMinutes: 1
reader:
host: postgres-reader
port: 5432
user: basyx_reader
password: change-me
dbname: basyx
sslmode: verify-full
sslrootcert: /run/secrets/postgres/ca.crt
maxOpenConnections: 60
maxIdleConnections: 30
connMaxLifetimeMinutes: 5
connMaxIdleTimeMinutes: 1
The reader supports the same connection and pool keys as the writer:
YAML key below |
Environment variable |
Default or requirement |
|---|---|---|
|
|
Optional complete reader connection string. |
|
|
Required when |
|
|
|
|
|
No writer-value inheritance. |
|
|
No writer-value inheritance. |
|
|
Required when |
|
|
Empty uses the PostgreSQL driver behavior. |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Empty uses |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Use either postgres.reader.dsn or the individual reader connection fields,
not both. Reader settings do not inherit connection fields or pool limits from
the writer. Omitting the complete reader configuration reuses the writer pool
and leaves reader routing disabled. Pointing both configurations
to the same PostgreSQL endpoint is also supported, but does not add database
read capacity and both pools then consume the same server connection budget.
A physical standby is a separate PostgreSQL instance that replicates the same
database, not an independent database.
Reader routing is supported by:
AAS Registry
Submodel Registry
Discovery Service
Digital Twin Registry
AAS Repository
Submodel Repository
Concept Description Repository
AAS Environment, including the repository, registry, and discovery APIs it hosts
AASX File Server
Company Lookup Service
DPP API
Eligible retrieval requests use the reader. This decision is based on the operation’s consistency requirements, not on the number of SQL queries needed to complete a request. Mutations, mutation guards and prechecks, transactions, read-after-write paths, schema validation, asynchronous jobs, operation invocation, authorization policy storage, and upload or binary staging remain on the writer. The Configuration Service and History Evidence Verifier are writer-only.
Configuring a reader opts the service into eventual consistency. PostgreSQL replication lag can make a successful write appear later through a reader-routed request. The same applies to deletions and authorization-relevant attribute changes: the current authorization middleware and filters are still applied, but a reader can briefly return the preceding resource state after access should have been revoked. Deployments that require immediate revocation or read-after-write consistency must omit the reader for the affected service or use replication guarantees that meet their required consistency window.
Compound responses are assembled in one read-only repeatable-read transaction. This keeps all SQL queries for that response on one reader connection and one database snapshot, so a resource is not combined from different replica positions. Separate requests can still observe different replay positions.
Both configured pools must be reachable during service startup. A reader outage after startup is not silently routed to the writer. In production:
use distinct writer and reader endpoints provided by a PostgreSQL operator or managed service;
use TLS with server verification and Secret-backed credentials;
grant the reader role only the permissions needed by reader-routed operations where feasible. For endpoints that are not inherently read-only, consider setting
postgres.reader.optionsto-c default_transaction_read_only=onas an additional guard;monitor replica health and replay lag;
test failover and recovery behavior for the selected PostgreSQL platform.
The pool settings apply independently to every process or Kubernetes pod. Calculate the connection budget separately for each PostgreSQL primary, including only clients that connect to that primary:
required application connections =
sum(maxOpenConnections per BaSyx service × maximum concurrent replica count)
+ non-BaSyx application pools
Non-BaSyx clients include identity services such as Keycloak when they share the database. The maximum concurrent replica count must include temporary old and new pods during rolling updates. Keep the total below that primary’s usable connection budget and reserve connections for administration, monitoring, migrations, and failover. The maximum is a limit rather than a guarantee that every pool always opens that many connections, but PostgreSQL must be able to handle the configured worst case. Idle connections are still open PostgreSQL sessions.
When a separate reader endpoint is configured, calculate its budget independently:
required reader connections =
sum(reader.maxOpenConnections per BaSyx service × maximum concurrent replica count)
+ non-BaSyx reader clients
Keep this total below the reader endpoint’s usable connection budget and reserve capacity for monitoring, administration, and failover. More pools or connections do not add CPU, storage I/O, or replication capacity.
All four pool values must be non-negative. An explicitly configured maxIdleConnections greater than the effective maxOpenConnections is rejected during startup. If maxIdleConnections is 0 and an explicit open limit is smaller than the default idle limit of 25, the effective idle limit is capped at that smaller open limit.
Helm Chart Configuration#
Note
The database.* values in this section are BaSyx Helm chart values, not Go
application configuration keys. Consult the chart’s
values.yaml
for the available settings and defaults in your installed chart version.
Optional CloudNativePG read-write connection pooler#
Note
The database.pooler values require BaSyx Helm chart 3.7.0 or newer. They
configure a CloudNativePG Pooler resource and are not BaSyx application YAML
settings.
For a database managed by the chart, an optional read-write PgBouncer layer can decouple the number of client connections opened by horizontally scaled BaSyx pods from the number of PostgreSQL server processes:
database:
pooler:
enabled: true
instances: 2
poolMode: transaction
maxClientConn: 1000
defaultPoolSize: 25
preparedStatements:
enabled: true
maxPreparedStatements: 100
parameters:
reserve_pool_size: "5"
resources:
requests:
cpu: 250m
memory: 256Mi
nodeSelector: {}
affinity: {}
tolerations: []
topologySpreadConstraints: []
The core pooler values and their defaults are:
Key |
Default |
Purpose |
|---|---|---|
|
|
Renders the managed read-write Pooler and routes eligible runtime services through it. |
|
|
Number of PgBouncer pods. |
|
|
PgBouncer pooling mode: |
|
|
Maximum client connections accepted by each PgBouncer pod. |
|
|
Default PostgreSQL server connections per PgBouncer pod and user/database pair. |
|
|
Enables PgBouncer protocol-level prepared-statement tracking. |
|
|
Maximum tracked prepared statements when tracking is enabled. |
|
|
Additional PgBouncer parameters as lowercase keys with string values. |
|
|
Requests and limits for the PgBouncer container. |
|
|
Node labels used to place Pooler pods. |
|
|
Node, pod, and pod anti-affinity for Pooler pods. |
|
|
Tolerations for Pooler pods. |
|
|
Topology-spread constraints for Pooler pods. |
When enabled, eligible services connect to
<database.clusterName>-rw-pooler. The chart replaces only POSTGRES_HOST;
the port, database name, user, password, and other settings still come from the
managed cluster’s application Secret. For long cluster names, the chart
truncates the cluster-name portion of the Pooler service name to keep the
generated name within 63 characters and distinct from the CloudNativePG
Cluster name.
The routing rules are intentionally narrower than a global host replacement:
BaSyx runtime services that use the global managed database connect through the Pooler.
The Configuration Service wait and migration containers connect directly to the CloudNativePG read-write service. Migrations use session-level advisory locks and must not run through transaction pooling.
Keycloak keeps its direct JDBC connection to the read-write service.
A service with its own
databaseoverride, whether inline or throughexistingSecret, keeps the host from that override and is not redirected.database.type=externalnever renders or uses this Pooler. If an external database needs PgBouncer, operate it separately and put its endpoint in the external database Secret.
Transaction pooling requires prepared-statement tracking for clients that use
protocol-level prepared statements. The chart therefore renders
max_prepared_statements=100 by default. Setting
preparedStatements.enabled=false explicitly renders
max_prepared_statements=0 and should only be done after verifying that the
complete workload does not need prepared statements. The first-class client
limit, server pool size, and prepared-statement values take precedence if the
same keys are also present under parameters. Additional parameters must be
supported by the PgBouncer version bundled with the installed CloudNativePG
operator.
Size the client side and server side separately. The aggregate application pool limit should fit within the Pooler client capacity with headroom for uneven load, rolling updates, and a failed Pooler pod:
sum(maxOpenConnections per BaSyx pod × maximum concurrent replica count)
< surviving Pooler instances × maxClientConn
For one user/database pair and no additional server-pool parameters, a starting estimate for PostgreSQL connections is:
Pooler instances × (defaultPoolSize + reserve_pool_size)
+ direct Keycloak connections
+ migrations, monitoring, administration, and failover reserve
< PostgreSQL max_connections
Adjust the estimate for every active user/database pair and for additional
PgBouncer limits. A Pooler queues excess client work; it does not add write
capacity to the PostgreSQL primary. If latency remains high, compare the BaSyx
PostgreSQL pool metrics
with cnpg_pgbouncer_* metrics and PostgreSQL query, lock, storage, and CPU
data before increasing the server pool.
Before enabling transaction pooling in production, render the chart against the installed CloudNativePG CRDs and test the deployed BaSyx version through the Pooler. Include bulk endpoints, large-object operations, connection saturation, rolling updates, and a PostgreSQL switchover.
Reader configuration and read-only Pooler#
Note
Both the chart-managed reader and its read-only Pooler are disabled by default.
These database.reader.* values are Helm chart values, not the application’s
postgres.reader.* YAML settings. The database.reader.* values require BaSyx Helm chart 3.9.0 and BaSyx Go
release 1.0.7 or newer.
For a database managed by the chart, enabling the global reader routes
reader-eligible requests to the CloudNativePG read-only service
<database.clusterName>-ro. Enabling its Pooler additionally creates a
CloudNativePG Pooler of type ro, changes the reader endpoint to
<database.clusterName>-ro-pooler, and leaves writer routing unchanged. For
long cluster names, the chart truncates the cluster-name portion of the Pooler
service name to keep it within 63 characters and distinct from the
CloudNativePG Cluster name:
database:
instances: 3
reader:
enabled: true
maxOpenConnections: 50
maxIdleConnections: 25
pooler:
enabled: true
instances: 2
monitoring:
enabled: true
labels:
release: kube-prometheus-stack
The global reader connection values are:
Key |
Default |
Purpose |
|---|---|---|
|
|
Injects the optional reader connection into supported BaSyx Go services. |
|
|
Complete external reader Secret. |
|
|
External reader host override. |
|
|
External reader port override. |
|
|
External reader database-name override. |
|
|
External reader user override. |
|
|
External reader password override. |
|
|
Reader TLS mode override. |
|
|
Reader client-certificate path override. |
|
|
Reader client-key path override. |
|
|
Reader root-CA path override. |
|
|
Reader connection-timeout override. |
|
|
Reader application-name override. |
|
|
Reader fallback application-name override. |
|
|
Reader search-path override. |
|
|
Reader PostgreSQL startup-options override. |
|
|
Reader session-time-zone override. |
|
|
Reader pool’s maximum open connections per BaSyx pod. |
|
|
Reader pool’s maximum idle connections per BaSyx pod. |
|
|
Reader connection lifetime. |
|
|
Reader idle lifetime; |
For an external database, database.reader.existingSecret selects a complete
reader Secret. It must contain host, port, dbname, user, and password
and can contain sslmode, sslcert, sslkey, sslrootcert,
connectTimeoutSeconds, applicationName, fallbackApplicationName,
searchPath, options, and timezone. Do not combine existingSecret with
inline reader connection fields. Inline reader connection values are stored in
a generated Secret. Any omitted inline field is deliberately sourced from the
effective writer Secret. This makes a host-only override possible without
duplicating credentials:
database:
type: external
existingSecret: basyx-postgres-writer
reader:
enabled: true
host: postgres-reader.example.internal
sslmode: verify-full
Setting only database.reader.enabled: true for an external database points
both pools to the same endpoint. This is valid for migration and compatibility
but does not add database capacity. Prefer a complete existing reader Secret,
TLS with server verification, and a least-privilege read-only role where
feasible in production.
Each charted BaSyx Go service supports a local override at
<component>.database.reader:
Component value |
Service |
|---|---|
|
Discovery Service |
|
AAS Registry |
|
AAS Repository |
|
AAS Environment |
|
DPP API |
|
Submodel Registry |
|
Submodel Repository |
|
Concept Description Repository |
|
Company Lookup Service |
|
Digital Twin Registry |
A service-local reader object replaces the global reader configuration. A reader-only local override continues to use the global writer. A service-local writer override without a local reader disables inherited global reader routing so that the service cannot accidentally read from a different database. The Configuration Service and Keycloak never receive the reader environment. The Go AASX File Server supports reader routing, but this chart does not currently deploy it.
The read-only Pooler accepts the same capacity, prepared-statement, placement, and monitoring values as the read-write Pooler:
database.reader.pooler.enableddatabase.reader.pooler.instancesdatabase.reader.pooler.poolModedatabase.reader.pooler.maxClientConndatabase.reader.pooler.defaultPoolSizedatabase.reader.pooler.preparedStatements.enableddatabase.reader.pooler.preparedStatements.maxPreparedStatementsdatabase.reader.pooler.parametersdatabase.reader.pooler.resourcesdatabase.reader.pooler.nodeSelectordatabase.reader.pooler.affinitydatabase.reader.pooler.tolerationsdatabase.reader.pooler.topologySpreadConstraintsdatabase.reader.pooler.monitoring.*
The schema requires database.instances to be at least 2 when a managed
reader implicitly targets the chart’s native <database.clusterName>-ro
service, because one instance provides no standby. A managed writer with one
instance can still use an explicit reader host or existingSecret. The
schema also rejects a read-only Pooler when the reader is disabled or when
database.type=external. Its PodMonitor renders only when both the Pooler
and its monitoring are enabled. It uses the cnpg.io/poolerName selector and
supports the same labels, annotations, interval, timeout, namespace selector,
relabelings, and metric relabelings as the read-write Pooler monitor.
Prometheus Operator and its monitoring.coreos.com/v1 CRDs must already be
installed.
Budget Pooler clients and PostgreSQL server connections separately. The sum of
the reader pool limits across all BaSyx pods must fit within the surviving
read-only Pooler instances’ client capacity. The Pooler server-pool sizes,
including every active user/database pair, must fit within the destination
standby’s max_connections with operational headroom. Monitor BaSyx
db.client.connections.* metrics, cnpg_pgbouncer_* metrics, and PostgreSQL
replication lag before increasing either limit.
The DSN and database credentials are sensitive and should normally be supplied through a secret rather than committed to YAML.
Application Configuration: HTTP and Features#
cors#
Key |
Default |
Purpose |
|---|---|---|
|
|
Allowed CORS origins. |
|
|
Allowed HTTP methods. |
|
|
Allowed request headers. |
|
|
Enables credentialed CORS requests. |
If-Match and If-None-Match are always allowed request headers, and ETag is exposed to browser clients, independently of allowedHeaders.
oidc and abac#
These fields are shared configuration; their presence does not mean every
executable installs runtime security middleware. The supported path is
activated through abac.enabled.
Key |
Default |
Purpose |
|---|---|---|
|
|
Path to the JSON trustlist of accepted OIDC providers. Required by participating services when ABAC is enabled. |
|
|
Enables OIDC authentication and ABAC authorization middleware. |
|
|
Path to the ABAC access-rules file. PostgreSQL-backed policy services use it for startup imports; the DPP API reads it directly. |
|
|
For PostgreSQL-backed policy services, controls startup import of |
|
|
Optional database namespace for stored ABAC policies. An empty value uses the service’s built-in scope. It does not apply to the file-backed DPP policy. |
|
|
Enables the protected API for managing the active PostgreSQL-backed ABAC policy. It does not apply to the DPP API. |
If abac.enabled is false, the shared security setup is skipped. If it is true, the trustlist is required. On services with PostgreSQL-backed policy storage, policyFileImport determines whether the policy file is loaded on every start, only if the database has no active policy, or never. policyScope controls that stored policy’s namespace; use different scopes to isolate deployments that share a database, and share a scope only when services should intentionally use the same active policy. The DPP API instead loads modelPath as its active file-backed policy and does not use policyFileImport, policyScope, or the policy-management API.
The startup modes have these exact effects:
Mode |
Startup import and persisted-policy behavior |
|---|---|
|
Read and import |
|
Import only when the effective scope has no active policy; otherwise continue using the active PostgreSQL policy. A file edit plus restart is therefore not sufficient once a policy exists. |
|
Never import |
For PostgreSQL-backed policy services, an empty mode is service-specific:
Digital Twin Registry resolves it to always; the others resolve it to
if_missing.
When set, policyScope is trimmed, must not exceed 255 characters, and may contain ASCII letters, digits, _, -, ., and :.
rebac#
Relationship-based access control (ReBAC) is experimental. It lets users share their own resources with other users or groups without editing the ABAC policy. On supported routes for authenticated callers, ReBAC can grant a right that ABAC has not granted unconditionally; that ReBAC grant is not restricted by ABAC’s conditional filter for the same right. See Relationship-Based Access Control for setup and operation.
Key |
Default |
Purpose |
|---|---|---|
|
|
Enables ReBAC. Requires |
|
|
Top-level access token claim with a stable user identifier. Use |
|
|
Top-level access token claim with group names. Use |
|
|
Bootstrap and recovery administrators as |
With rebac.enabled=false, no ReBAC code is wired and services behave exactly as before. When ReBAC is enabled, subjectClaim and groupClaim must not be empty, and every administrators entry must contain an issuer and a subject or a non-empty group name separated by |. A service with ReBAC enabled refuses to start without ABAC (REBAC-SETUP-ABACREQUIRED) or OIDC (REBAC-SETUP-OIDCREQUIRED).
Relationships are stored in the BaSyx PostgreSQL database. If multiple ReBAC-capable BaSyx services share that database, enable ReBAC consistently across them. Company Lookup and Digital Twin Registry do not support ReBAC and always run with ReBAC disabled.
OIDC trustlist provider fields#
Entries in the JSON file at oidc.trustlistPath support the following fields. They are not additional keys in the main YAML oidc section.
Field |
Purpose |
|---|---|
|
OIDC issuer URL whose tokens are accepted. |
|
Optional required token audience. Audience validation is skipped when this is empty. |
|
Scopes that an accepted token must provide. |
|
Optional non-standard OpenID Provider discovery URL. |
|
Optional JSON pointers identifying claims from which OAuth scopes are read. |
|
Optional rules that map provider-specific claims into canonical BaSyx claims. |
Each claimMappings entry contains:
Field |
Purpose |
|---|---|
|
Target claim name without the |
|
Mapping mode: |
|
Provider claim paths used as mapping inputs. |
general#
Key |
Default |
Purpose |
|---|---|---|
|
|
Allows implicit casts in ABAC/query expression evaluation. |
|
|
Enables descriptor query debug output. |
|
|
When AAS Descriptors are written, also maintains the asset-identifier-to-AAS-identifier records used by Discovery lookups. |
|
|
Enables the EDC BPN header-to-claim middleware in the standalone Submodel Repository and Digital Twin Registry. |
|
|
For Submodel Descriptors, accepts the compatibility field name |
|
|
Makes AAS Repository changes maintain matching AAS Descriptor records in PostgreSQL so an AAS Registry using the same database can expose them. This is not an HTTP connection to the Registry. |
|
|
Makes Submodel Repository changes maintain matching Submodel Descriptor records in PostgreSQL so a Submodel Registry using the same database can expose them. This is not an HTTP connection to the Registry. |
|
|
Comma-separated public base URL(s). All entries generate endpoints in synchronized Registry descriptors; the first entry is also used for externally reachable resource and |
|
|
Allows |
|
|
CIDR allowlist for proxies whose forwarded headers may be trusted. An empty list means forwarded headers are never trusted, even when |
|
|
Maximum content size in bytes for shared binary uploads and the |
|
|
Maximum JSON response size in bytes from a delegated Submodel Operation. Applies to synchronous and asynchronous invocation in the Submodel Repository and AAS Environment. |
|
|
Maximum number of non-directory entries in an AASX package. |
|
|
Maximum combined expanded size of AASX OPC metadata. |
|
|
Maximum expanded size of one AASX payload part; also limits the JSON or XML specification produced by Environment serialization, including plain JSON/XML exports. |
|
|
Maximum combined expanded size of all AASX payload parts. |
|
|
Maximum expanded size of an AASX thumbnail. |
|
|
AAS Environment startup import sources. Supports files or folders with |
|
|
Maximum row count per generated bulk SQL statement. Must be greater than |
uploadMaxSizeBytes limits the transmitted file part, not the complete multipart HTTP request. The request parser separately allows bounded space for multipart metadata and framing. The AASX settings independently limit expanded package content to protect against packages whose contents are much larger than the uploaded file. uploadMaxSizeBytes and all five aasxMax* values must be greater than 0. In addition, aasxMaxTotalExpandedSizeBytes must be greater than or equal to aasxMaxPartExpandedSizeBytes, which must be greater than or equal to aasxMaxThumbnailSizeBytes.
Environment exports limit the JSON or XML specification, including the specification part inside an AASX package, using aasxMaxPartExpandedSizeBytes (default 128 MiB). AASX exports also enforce the package-part count, expanded-total, and thumbnail limits listed above. Exceeding an export limit returns 413 Request Entity Too Large. The same response applies when the estimated storage for referenced Concept Description identifiers exceeds a fixed 16 MiB limit, which is not configurable. general.aasxMaxOPCMetadataSizeBytes applies when reading/importing AASX packages. It is not enforced during export.
delegatedOperationResponseMaxSizeBytes defaults to 1 MiB. Set a larger positive byte count when a delegated Operation returns more data, such as records. The response is buffered in memory, so size the limit for the available memory. File element attachment downloads are unaffected.
When registry synchronization is enabled, general.externalUrl must contain at least one absolute HTTP(S) URL with a scheme and host; query strings and fragments are rejected. DPP serialization of a managed attachment also requires a valid first URL. AAS Descriptor writes use discoveryIntegration when performed directly by an AAS Registry or through repository-to-registry synchronization. AAS Environment and Digital Twin Registry enable discovery integration internally.
jws and swagger#
Key |
Default |
Purpose |
|---|---|---|
|
|
RSA private key used by AAS Repository, Submodel Repository, and AAS Environment signed reads. |
|
|
PEM-encoded X.509 certificate chain included as the JWS |
|
|
Enables Swagger UI and OpenAPI specification endpoints. |
|
|
Contact name injected into OpenAPI/Swagger docs. |
|
|
Contact email injected into OpenAPI/Swagger docs. |
|
|
Contact URL injected into OpenAPI/Swagger docs. |
history#
History settings control API history, audit metadata, and optional external evidence storage. A component must implement history handling for these settings to have a runtime effect.
Key |
Default |
Purpose |
|---|---|---|
|
|
History mode: |
|
|
Requested database-history retention. Only |
|
|
Number of history rows between full snapshots. Must be at least |
|
|
Immutability mode: |
|
|
Identity detail stored with audit entries: |
|
|
External integrity-anchor backend. Only |
external_anchor cannot currently be used: it requires a non-none integrity-anchor provider, while no such provider is implemented yet.
Warning
postgres_guarded is not a process-local toggle. When history is active, a
service using it establishes a database-wide guard in PostgreSQL. That guard is
persistent and a later process configured without guarded immutability cannot
simply reset it; an incompatible startup can fail. Merely setting
immutability: postgres_guarded while history.mode is off does not
establish the guard. Diagnose both the effective process configuration and the
existing database state. See Database-wide history guard.
history.evidence#
Evidence storage writes WORM-compatible history artifacts to object storage.
Key |
Default |
Purpose |
|---|---|---|
|
|
Enables external evidence artifact writing. Independent of |
|
|
Evidence backend. Accepted values are |
|
|
S3 bucket that receives evidence artifacts. Required when evidence is enabled. |
|
|
Object-key prefix used inside the bucket. |
|
|
S3 region. Required when evidence is enabled. |
|
|
Optional custom S3-compatible endpoint, for example a MinIO endpoint. |
|
|
Optional explicit S3 access-key ID. Configure it together with |
|
|
Optional explicit S3 secret access key. Configure it together with |
|
|
Uses path-style S3 addressing instead of virtual-hosted bucket addressing. Often needed for local S3-compatible services. |
|
|
S3 Object Lock mode: |
|
|
Object-lock retention period. Must be at least |
|
|
Timeout for writing an evidence artifact. Must be at least |
|
|
Private key used to sign evidence manifests. If empty, |
|
|
Public key used for evidence-signature verification. |
|
|
Requires signing material. At least a signing private key, the JWS fallback key, or a public key must be configured. |
Credentials are sensitive. Prefer secret-backed environment variables or mounted secret files over committing them to YAML.
eventing#
Eventing is experimental. It publishes AAS, asset, Submodel, and PCN changes as CloudEvents through MQTT 5, Kafka, and AMQP 1.0 brokers, or makes them available through the REST Event Feed. The AAS Repository, Submodel Repository, and AAS Environment support eventing.
Key |
Default |
Purpose |
|---|---|---|
|
|
Enables event publishing to broker transports. |
|
|
Event serialization format. Only |
|
|
Broker transports: |
|
|
Enables the transactional outbox that stores pending events in PostgreSQL. Required by every transport. |
|
|
Prefix of the generated MQTT topics. It must not contain |
|
|
Optional event source base URL. Defaults to the first |
|
|
Optional base URL of the event payload schemas. Defaults to the source base URL followed by |
A non-empty sinks list requires both enabled and outboxEnabled. An enabled outbox requires at least one sink. Sink names must be unique, and every transport must use a distinct sinkId. sourceBaseUrl and schemaBaseUrl must be absolute HTTP(S) URLs without credentials, query, or fragment.
Event delivery is at least once. Consumers should deduplicate by CloudEvents ID. Pending events are retried indefinitely and do not expire, so allow database capacity for broker outages. Drain pending deliveries before changing the broker, sink ID, or destination of a transport.
Credential and TLS settings are available for every transport. Supply either a credential value or its file, not both. Files are read at startup, and trailing line endings are removed. Client certificate and key files must be supplied together. TLS requires TLS 1.2 or later and verifies the server certificate.
eventing.mqtt#
Key |
Default |
Purpose |
|---|---|---|
|
|
Required. Broker URL |
|
|
Required. MQTT client ID. It must be unique for each process connecting to the broker, including replicas. |
|
|
Stable identifier of the delivery queue. Replicas sharing a database use the same value. |
|
|
MQTT QoS: |
|
|
Publishes retained messages. |
|
|
Optional broker credentials. |
|
|
Files containing the broker credentials. |
|
|
Optional PEM CA bundle. Requires a |
|
|
Optional client certificate and key for mutual TLS. Requires a |
eventing.kafka#
Key |
Default |
Purpose |
|---|---|---|
|
|
Required bootstrap brokers as |
|
|
Topic for all event families. Create it before enabling the sink. |
|
|
Stable identifier of the delivery queue. |
|
|
Client name reported to Kafka. |
|
|
Maximum uncompressed batch size. |
|
|
Enables TLS. |
|
|
Optional PEM CA bundle. Requires |
|
|
Optional client certificate and key for mutual TLS. Requires |
|
|
Empty disables SASL. Supported values are |
|
|
SASL credentials. Required when |
|
|
Files containing the SASL credentials. |
eventing.amqp#
Key |
Default |
Purpose |
|---|---|---|
|
|
Required. Broker URL |
|
|
Required target address, for example |
|
|
Stable identifier of the delivery queue. |
|
|
Optional AMQP connection hostname. RabbitMQ selects a virtual host with |
|
|
Optional SASL PLAIN credentials. Supply both or neither. |
|
|
Files containing the SASL PLAIN credentials. |
|
|
Optional PEM CA bundle. Requires |
|
|
Optional client certificate and key for mutual TLS. Requires |
eventing.feed#
The REST Event Feed is independent of eventing.enabled and the broker transports. When enabled, it adds GET /events, GET /.well-known/event-feed.json, and the schema endpoints to the service.
Key |
Default |
Purpose |
|---|---|---|
|
|
Enables the REST Event Feed. |
|
|
Visible retention window in days, measured from the mutation time. |
|
|
Additional days before expired events are physically deleted. |
|
|
Compatible alias of |
|
|
Compatible alias of |
|
|
Interval of the physical cleanup. Cleanup also runs at startup. |
|
|
Interval before checking for committed events to publish to the feed. |
maxAgeDays, hardDeleteGraceDays, and publishIntervalMillis must not be negative. The page size of GET /events follows server.pagination.defaultLimit and server.pagination.maxLimit; the former eventing.feed.maxPageSize setting no longer exists and is ignored if present.
mcp#
The MCP endpoint is experimental and only served by the AAS Environment. It lets MCP clients such as AI agents read and change AAS data through the Environment’s REST API. See MCP Endpoint for tools, client setup, and sign-in.
Key |
Default |
Purpose |
|---|---|---|
|
|
Serves the MCP endpoint at |
|
|
Endpoint path below |
|
|
Also offers the tools that create, change, and delete data. |
|
|
Largest API response in bytes that a tool returns. Larger read results fail. |
path must start with /, must not be / or end with /, and must not contain ?, #, %, {, }, *, or ... maxResultBytes must be at least 1024. With abac.enabled=true, every trustlist entry must define an audience; otherwise the AAS Environment does not start while the MCP endpoint is enabled.
Example YAML#
logging:
format: text
level: info
server:
host: 0.0.0.0
port: 5004
contextPath: ""
cacheEnabled: false
strictVerification: permissive
verificationEndpointAvailable: true
readHeaderTimeoutSeconds: 15
readTimeoutSeconds: 300
writeTimeoutSeconds: 300
idleTimeoutSeconds: 60
shutdownTimeoutSeconds: 10
pagination:
defaultLimit: 100
maxLimit: 1000
conditionalRequests:
requireIfMatch: false
postgres:
dsn: ""
host: db
port: 5432
dbname: basyxTestDB
user: admin
password: admin123
sslmode: disable
sslcert: ""
sslkey: ""
sslrootcert: ""
connectTimeoutSeconds: 0
applicationName: ""
fallbackApplicationName: ""
searchPath: ""
options: ""
timezone: ""
maxOpenConnections: 50
maxIdleConnections: 25
connMaxLifetimeMinutes: 5
connMaxIdleTimeMinutes: 0
cors:
allowedOrigins: []
allowedMethods: [GET, POST, PUT, PATCH, DELETE, OPTIONS]
allowedHeaders: []
allowCredentials: false
oidc:
trustlistPath: "config/trustlist.json"
abac:
enabled: false
modelPath: "config/access_rules/access-rules.json"
policyFileImport: ""
policyScope: ""
managementApi:
enabled: false
rebac:
enabled: false
subjectClaim: sub
groupClaim: groups
administrators: []
general:
enableImplicitCasts: true
enableDescriptorDebug: false
discoveryIntegration: false
enableCustomMiddlewareHeaderInjection: false
supportsSingularSupplementalSemanticId: false
aasRegistryIntegration: false
submodelRegistryIntegration: false
externalUrl: ""
trustProxyHeaders: false
trustedProxyCIDRs: []
uploadMaxSizeBytes: 134217728
delegatedOperationResponseMaxSizeBytes: 1048576
aasxMaxPartCount: 10000
aasxMaxOPCMetadataSizeBytes: 16777216
aasxMaxPartExpandedSizeBytes: 134217728
aasxMaxTotalExpandedSizeBytes: 536870912
aasxMaxThumbnailSizeBytes: 16777216
aasPreconfigPaths: []
bulkBatchLimit: 1000
jws:
privateKeyPath: ""
certificateChainPath: ""
swagger:
enabled: true
contactName: "Eclipse BaSyx"
contactEmail: "basyx-dev@eclipse.org"
contactUrl: "https://basyx.org"
history:
mode: off
retentionDays: 0
fullSnapshotInterval: 1
immutability: none
auditIdentityMode: none
evidence:
enabled: false
provider: none
bucket: ""
prefix: basyx-history-evidence
region: us-east-1
endpoint: ""
accessKeyId: ""
secretAccessKey: ""
pathStyle: false
retentionMode: ""
retentionDays: 0
writeTimeoutSeconds: 10
signing:
privateKeyPath: ""
publicKeyPath: ""
required: false
integrityAnchor:
provider: none
eventing:
enabled: false
format: cloudevents
sinks: []
outboxEnabled: false
topicPrefix: basyx
sourceBaseUrl: ""
schemaBaseUrl: ""
mqtt:
broker: ""
clientId: ""
sinkId: mqtt
qos: 1
retained: false
username: ""
password: ""
usernameFile: ""
passwordFile: ""
caFile: ""
certificateFile: ""
keyFile: ""
kafka:
brokers: []
topic: basyx.events
sinkId: kafka
clientId: basyx
producerBatchMaxBytes: 0
tlsEnabled: false
caFile: ""
certificateFile: ""
keyFile: ""
saslMechanism: ""
username: ""
password: ""
usernameFile: ""
passwordFile: ""
amqp:
broker: ""
address: ""
sinkId: amqp
hostName: ""
username: ""
password: ""
usernameFile: ""
passwordFile: ""
caFile: ""
certificateFile: ""
keyFile: ""
feed:
enabled: false
maxAgeDays: 30
hardDeleteGraceDays: 10
sourceBaseUrl: ""
schemaBaseUrl: ""
cleanupIntervalHours: 24
publishIntervalMillis: 250
mcp:
enabled: false
path: /mcp
writesEnabled: false
maxResultBytes: 262144
Environment Variables#
For regular settings, use the uppercase YAML path with dots replaced by underscores:
LOGGING_FORMAT=text
LOGGING_LEVEL=info
SERVER_PORT=5004
SERVER_CONTEXTPATH=/api
SERVER_STRICTVERIFICATION=permissive
SERVER_READ_HEADER_TIMEOUT_SECONDS=15
SERVER_READ_TIMEOUT_SECONDS=300
SERVER_WRITE_TIMEOUT_SECONDS=300
SERVER_IDLE_TIMEOUT_SECONDS=60
SERVER_SHUTDOWN_TIMEOUT_SECONDS=10
SERVER_PAGINATION_DEFAULT_LIMIT=100
SERVER_PAGINATION_MAX_LIMIT=1000
SERVER_CONDITIONALREQUESTS_REQUIREIFMATCH=false
POSTGRES_HOST=db
POSTGRES_PORT=5432
POSTGRES_USER=admin
POSTGRES_PASSWORD=admin123
POSTGRES_DBNAME=basyxTestDB
POSTGRES_SSLMODE=disable
POSTGRES_CONNECTTIMEOUTSECONDS=10
POSTGRES_MAXOPENCONNECTIONS=50
POSTGRES_MAXIDLECONNECTIONS=25
POSTGRES_CONNMAXLIFETIMEMINUTES=5
POSTGRES_CONNMAXIDLETIMEMINUTES=0
ABAC_ENABLED=false
ABAC_POLICYFILEIMPORT=if_missing
ABAC_POLICY_SCOPE=aasregistryservice
ABAC_MANAGEMENTAPI_ENABLED=false
REBAC_ENABLED=false
OIDC_TRUSTLISTPATH=config/trustlist.json
GENERAL_EXTERNALURL=https://example.org/aas
GENERAL_TRUSTPROXYHEADERS=false
GENERAL_UPLOADMAXSIZEBYTES=134217728
GENERAL_DELEGATEDOPERATIONRESPONSEMAXSIZEBYTES=1048576
GENERAL_AASXMAXPARTCOUNT=10000
GENERAL_AASXMAXOPCMETADATASIZEBYTES=16777216
GENERAL_AASXMAXPARTEXPANDEDSIZEBYTES=134217728
GENERAL_AASXMAXTOTALEXPANDEDSIZEBYTES=536870912
GENERAL_AASXMAXTHUMBNAILSIZEBYTES=16777216
GENERAL_BULK_BATCH_LIMIT=1000
SWAGGER_ENABLED=true
MCP_ENABLED=false
MCP_PATH=/mcp
MCP_WRITESENABLED=false
MCP_MAXRESULTBYTES=262144
GENERAL_AAS_PRECONFIG_PATHS is parsed as a comma-separated list and overrides general.aasPreconfigPaths:
GENERAL_AAS_PRECONFIG_PATHS=file:/data/example.aasx,/data/preconfigured-aas
Automatically derived environment variables for other string-list fields are
also comma-separated. This applies, for example, to CORS_ALLOWEDORIGINS,
CORS_ALLOWEDMETHODS, CORS_ALLOWEDHEADERS, and
GENERAL_TRUSTEDPROXYCIDRS. The dedicated parsers for
GENERAL_AAS_PRECONFIG_PATHS and BASYX_EVENTING_SINKS additionally trim
surrounding whitespace and discard empty entries.
The following explicit aliases are also supported:
YAML setting |
Environment variable |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
The legacy Viper-derived names without word-separating underscores, such as SERVER_READTIMEOUTSECONDS, remain supported. The explicit aliases are applied after normal environment-variable decoding and therefore take precedence when both forms are set.
To use a complete PostgreSQL DSN, set only POSTGRES_DSN for the connection details. Do not also set individual connection variables such as POSTGRES_HOST or POSTGRES_SSLMODE:
POSTGRES_DSN=postgres://admin:secret@db:5432/basyx?sslmode=require
POSTGRES_MAXOPENCONNECTIONS=50
POSTGRES_MAXIDLECONNECTIONS=25
POSTGRES_CONNMAXLIFETIMEMINUTES=5
POSTGRES_CONNMAXIDLETIMEMINUTES=0
Security Files#
The shared configuration may reference these security-sensitive files:
oidc.trustlistPathabac.modelPathjws.privateKeyPathjws.certificateChainPathhistory.evidence.signing.privateKeyPathhistory.evidence.signing.publicKeyPathpostgres.sslcertpostgres.sslkeypostgres.sslrootcerteventing.mqtt.usernameFile,eventing.mqtt.passwordFile,eventing.mqtt.caFile,eventing.mqtt.certificateFile,eventing.mqtt.keyFileeventing.kafka.usernameFile,eventing.kafka.passwordFile,eventing.kafka.caFile,eventing.kafka.certificateFile,eventing.kafka.keyFileeventing.amqp.usernameFile,eventing.amqp.passwordFile,eventing.amqp.caFile,eventing.amqp.certificateFile,eventing.amqp.keyFile
In containers, paths are resolved inside the container filesystem. Mount the files or their parent directory and point the YAML value or environment variable to the mounted path.
Notes#
The BaSyx Configuration Service mainly uses the
postgressection.Repository, environment, and AASX File Server endpoints use
general.uploadMaxSizeBytesfor uploaded file-content limits.Submodel Repository and AAS Environment use
general.delegatedOperationResponseMaxSizeBytesfor delegated Submodel Operation responses.Services that process AASX packages use the
general.aasxMax*settings for expanded package limits.AAS Environment additionally supports
general.aasPreconfigPaths.AAS Repository, Submodel Repository, and AAS Environment use the registry synchronization settings when enabled.
AAS Repository, Submodel Repository, and AAS Environment use the
eventingsettings.Only the AAS Environment uses the
mcpsettings.AAS Repository, Submodel Repository, Concept Description Repository, AAS Registry, Submodel Registry, Discovery, AASX File Server, AAS Environment, and DPP API use the
rebacsettings. Company Lookup and Digital Twin Registry always disable ReBAC.