Master: ecmwf.properties¶

The Master's ecmwf.properties controls scheduling, database access, public services, operational events and shared infrastructure. This reference includes options read by the implementation even when they are absent from the shipped file.

Other services have separate references: Monitor and Data Mover.

Identity extensions¶

[AuthenticationExtension] class and [UserDirectoryExtension] class select trusted Master identity providers. A blank authentication class automatically selects the bundled ECMWF TOTP adapter when [TOTP] active=true; otherwise it preserves local WebUser password authentication. A nonblank class selects the configured provider. Set [AuthenticationExtension] required=yes to fail Master startup if no authentication provider is configured; it defaults to no. Provider-specific options belong in the same section. Configuration is read at startup and requires a restart; a configured provider that cannot start fails Master startup. See Identity extensions for installation, lifecycle and authentication precedence.

The optional ECaccess directory extension uses host and port in [UserDirectoryExtension] and requires explicit bounded [RMIClientSocketFactory] connection/read timeouts. It does not provide password/passcode authentication.

[RemoteServiceExtensions] explicitly maps service IDs to provider configuration sections. It defaults to no registrations. See Remote service extensions and the optional ECaccess transfer module.

[InteractiveLoginExtension] class independently enables browser-based Monitor login. It defaults to blank. [InteractiveLoginMapping] maps local WebUser IDs to JSON objects containing the verified external issuer and subject. See OpenID Connect login for the bundled provider, full configuration and account requirements.

File location and configuration layers¶

The source template is etc/master/conf/ecmwf.properties. RPM installations place it in /usr/local/ecpds/master/conf/ecmwf.properties. The launcher selects the file with the ecmwf.properties JVM property; container mounts can change where its contents are stored.

Use /etc/ecpds/master.cnf or the container/service environment for launcher settings such as addresses, ports, database connection details and secrets. The launcher translates supported variables into the JVM properties referenced by the template. Arbitrary environment variables do not automatically become ecmwf.properties options.

The final directive:

#include "${master.etc}/ecmwf.properties"

loads a local override file from the launcher's master.etc directory if it exists and is readable. Despite the leading #, #include is an active configuration directive, not an ordinary comment. It must start at the beginning of the line. The supplied service layout uses a separate directory for this file, normally /etc/ecpds/master; do not point an include back to the file containing it. An unreadable or missing include produces a warning.

An override contains only the sections and values to change, for example:

[TransferScheduler]
queueSize=80

[StoragePolicy]
enabled=no
interval=1m

Restart the affected service after changing configuration unless a feature's documentation explicitly describes runtime reload support. Many values are cached when classes or services initialize. #reload "Group" permits the configuration loader to reload that group, but does not make every consumer apply a changed value dynamically.

Syntax and defaults¶

Optional Master-only SNMP location collection uses [PhysicalLocation], [PhysicalLocationSystems], [PhysicalLocationMachine.ID] and [PhysicalLocationProfile.ID]. It is off by default and uses the physical-location tables included in the installation schema. See Physical system locations for target mappings, protected credential files, limits and RMI/display behavior.

The catalogue distinguishes code fallback (what a particular reader uses when the option is absent) from shipped value (what the template explicitly sets). They are not necessarily equal. Removing a setting can therefore change behaviour. A dash in the shipped column means it is not assigned in the template. null means that reader supplies no value, not that the option is safe to omit. An empty list and an empty string are shown explicitly.

Context-dependent Java expressions are retained rather than replaced by a guessed constant. Where readers use different fallbacks, they appear on separate rows with links to their source. File-content options interpret the configured value as a path, but their fallback is content. Shipped credentials are not reproduced here.

Entries marked template entry have no direct literal reader in the reviewed sources. They may be consumed through substitutions or retained for compatibility; their presence alone is not evidence of an active runtime switch. Named-socket and open-map readers are documented separately.

Operational guidance¶

• Enable native log export, journaling and tracing independently; see Event Logging. Only the Master needs Collector connectivity and OpenTelemetry connection settings.
• [StoragePolicy] enabled=yes can enforce existing policies immediately. Read Storage Lifecycle Policies before enabling it.
• Scheduler switches in [Server] enable workers; [Scheduler] configures their cadence, concurrency and watchdogs. Increasing concurrency also increases database, memory and Mover load.
• Repository *Size settings select storage-worker thread counts, not queue capacities or records per batch. Do not use them as retention limits.
• Keep RMI and callback interfaces on trusted networks. Public service bind addresses and advertised addresses serve different purposes.
• Protect credentials and keystores with restrictive file permissions. trustAllCerts, checkCertificates=no and plaintext proxy connections weaken transport protection; shipped values are not security recommendations.

Option catalogue¶

The following sections cover literal property readers, shared infrastructure, named socket overrides and dynamic option families in the OpenECPDS sources. Shared components only use their options when instantiated; listing a component does not enable it. Host, destination, user and transfer-module property families are linked below rather than conflated with service switches.

[API]¶

Template-defined configuration; see the reader links for its consuming component.

[CallBack]¶

Exported callback endpoint. serverFactory and clientFactory are Java socket-factory classes. This section also accepts the named socket overrides described below.

[Command]¶

External helper commands. ecauth overrides the token-generation executable; sh selects the ECios shell command.

[DataBase]¶

Database broker and JDBC configuration. initSleep is seconds; purge is hours and maxTransferLife is days. fetchSize is rows; retry delays are milliseconds. Broker-specific flags only apply to that broker. The shipped Hibernate broker deliberately differs from the generic broker fallback.

[ECaccessScheduler]¶

Shared scheduler's minimum wait duration.

[ECauthModule]¶

ECauth connection and host-list cache. Durations control connection timeout, refresh polling, refresh frequency and cached-entry lifetime. Credentials here identify the ECauth service account.

[ECauthSession]¶

Legacy fallback command for ECauth token generation; [Command] ecauth and [Server] ecauth take precedence.

[ECios]¶

ECios helper start/kill socket timeouts, in milliseconds. Also accepts named socket overrides.

[ECpdsBase]¶

Database-facing cache refresh pause and expiry durations.

[ECpdsClient]¶

ECpds socket-client read timeout in milliseconds. This is distinct from the server-side plugin timeout.

[ECpdsPlugin]¶

Master ECpds listener and request-processing behaviour. checkPort requires a privileged client source port when enabled. SocketSoTimeout applies to accepted request sockets in milliseconds. resetDataTransferSchedulesByGroup resets schedules on group completion. The section also accepts named socket options.

[ECproxyPlugin]¶

Mover ECproxy data listener and repository. Explicit TCP options override the accepted socket's existing values. Buffer sizes are bytes; socket timeouts are milliseconds. Also accepts named socket settings.

[ExecModule]¶

Defaults for the executable transfer module. script runs after file reception; dir falls back to the transfer directory. synchronous waits for command completion, returnCode is its accepted exit status, and usePipe supplies arguments on standard input. mkdirs creates parent directories and usetmp stages reception in a temporary file. Empty prefix and suffix select an effective .tmp suffix.

[ExecutorManager]¶

Opt-in virtual-thread execution for the shared executor. This is not a general scheduler concurrency limit.

[FTPActiveSocket]¶

FTP server active-data sockets. Accepts every named socket option below, in addition to these direct readers.

[FTPPassiveSocket]¶

FTP server passive-data sockets. boundAddress controls the address used for passive binding. Also accepts named socket settings, including local-port ranges.

[Filter]¶

Streaming compression/decompression command definitions. The four fly.* keys are read by the stream manager. The template also retains pre.out.* definitions, but the current source has no direct reader for those entries.

[FtpDomainList]¶

Virtual FTP/SFTP domain mappings; arbitrary domain names are supported. * is the fallback. Domain mappings select backing filesystem/domain implementations, not network listener addresses.

[FtpModuleList]¶

FTP extension-module lists. Keys select extensions; * supplies the default list. Values are comma-separated module definitions consumed by the FTP utility.

[FtpPlugin]¶

FTP control listener and behaviour. welcome, browser and help are file paths; tail is response text. passive, rest and extended affect FTP features. hidden is a list of hidden virtual domains. alwaysCheckOnRETR requests retrieval-time checks. The section also accepts named socket options.

[GeoIP]¶

Template-defined configuration; see the reader links for its consuming component.

[IO]¶

Local repository I/O implementation. byteBufferSizeInMb sets the buffer size in MiB; pool idle age is seconds. Direct buffers and pooling only apply when the byte-buffer path is used. channelForce, channelForceMetadata and fdSync govern persistence/sync behaviour; changing them trades durability and performance.

[InterruptibleRMIServerSideSocket]¶

Cleanup interval for server-side interruptible RMI socket state, in minutes.

[InterruptibleRMISocket]¶

Interruptible RMI stream-buffer pooling. Buffer size is bytes and buffer TTL is minutes.

[Login]¶

Component identity, registration credential and addresses. root defaults to the hostname in normal service readers. Several utility readers use their own hostname/service fallback, so removing identity settings is not recommended. External/internal addresses are primarily consumed through template references and named socket sections.

[LoginManagement]¶

Failed-login throttling and ban tracking. active enables enforcement; max is consecutive failures. timer, wait and the login-path delay are seconds. The cleanup thread also reads delay as a raw millisecond polling interval with a different fallback; both readers are shown. whitelist bypasses these checks for matching entries.

[Mail]¶

SMTP and optional mail-store configuration. host/user are the legacy shared defaults; smtpHost overrides the outgoing host. starttls, tls and auth affect transport/authentication. Store settings apply only to mail retrieval. Keep passwords in protected local configuration.

[Master]¶

Whether Master registration updates a Mover's ECproxy address and port.

[MetaData]¶

Metadata reload duration and notification recipient when contact information is missing.

[Monitor]¶

External service-status integration, independent of the web monitoring UI. activated enables it, debug logs submissions and dontSend suppresses delivery. delay is a duration: the template's bare 120 means 120 hours, whereas the code fallback is five minutes.

[NetworkWeather]¶

Network Weather admission/control limits. Values are counts except maxConfigurationBytes and maxControlResponseBytes, which are bytes. The Monitor controls activation; these settings bound accepted work rather than enabling probes.

[OpenTelemetry]¶

Master-only log, metric and trace SDK defaults. Metric intervals/timeouts and log/trace schedule delays are milliseconds; queue/batch limits count records or spans, and sample ratio is 0-1. Standard JVM/environment SDK settings override these defaults. With log journaling enabled, log queue/batch values govern only in-memory fail-open delivery, not the database backlog.

[OperationalEvents]¶

Independent Splunk-file and native OpenTelemetry event outputs. Journaling persists events before OTLP delivery; install the journal schema before enabling it. journalOwner must remain stable and distinguish independent Masters.

The warning and critical thresholds are positive values, and each warning value must be lower than its corresponding critical value. They are loaded at Master startup. Reaching either the pending-count or oldest-admission-age threshold raises the corresponding alert on the journal page.

[Operator]¶

Transfer-operation message template. $destination[...], $dataFile[...] and related placeholders are expanded from transfer context.

[OpsViewManager]¶

OpsView publication endpoints, credentials, filters and TLS verification. URLs default relative to url; filter names differ by acquisition/dissemination/other roles. trustAllCerts=true skips certificate validation.

[Other]¶

Shared utilities. buffer is an I/O buffer size in bytes; ticketWaitDuration is a raw millisecond timeout. ecauthTokenCache enables token caching. dontCheckIp bypasses the provider's client-address check during subscription. tmp is retained in templates; the launcher separately sets the JVM temporary directory.

[PluginList]¶

Template-defined configuration; see the reader links for its consuming component.

[Ports]¶

Template port substitutions. Most keys are only referenced by listener sections and therefore have no independent code default. ecpds also has a direct client-reader fallback.

[ProxySocket]¶

Proxy data/control socket settings. plainText chooses non-TLS transport and otherwise depends on the connection's addresses. host/port select the control endpoint; dataHost/dataPort can select the data endpoint separately. cipherSuites is the TLS suite list. Also accepts named socket options.

[RMIClientSocketFactory]¶

Template-defined configuration; see the reader links for its consuming component.

[RMIServerSocketFactory]¶

Template-defined configuration; see the reader links for its consuming component.

[RequestParser]¶

Optional parser-backed ECpds ingestion. parserDir holds parser files; requestSize is parser worker count, requestDelay is milliseconds and maxAuthorisedSize bounds pending requests. logRequests controls request logging, not operational-event platform selection.

[ResourceTracker]¶

Shared runtime-resource diagnostics. defaultDebugFrequency counts resource-close events between debug reports; it is not a time interval.

[Scheduler]¶

Worker cadence, concurrency and watchdogs. *JammedTimeout, maximumDuration* and timeOut* read durations; a negative timeout leaves that execution limit unset. *TimeRanges accepts configured execution windows. max*Threads values are concurrency counts; cacheRatio scales prefetch. The legacy purgeDataBase/updateECUsers intervals are hours, with optional clock-time lists.

[ScriptManager]¶

JavaScript/Graal engine settings. runningTimeout and longRunningTime are milliseconds. resourceLimits=0 leaves the statement limit disabled. Shared engines, compilation and virtual-thread execution are independent switches.

[Security]¶

Authentication, secret protection, socket TLS and optional HTTPS store defaults. SSL store readers can fall back to JVM javax.net.ssl.* properties; HTTPS has its own fallback path. JCE settings protect stored secrets and are not HTTPS cipher settings. checkCertificates=no disables certificate checks. See the TLS and control-channel guides before changing these values.

[Server]¶

Per-process service switches and local paths. Master readers enable schedulers/repositories; Mover readers enable its own repositories/accounting. dontRecord* suppresses management-action history, not native telemetry globally. Globe cache settings belong to the Monitor. providerMBeanTimeout is milliseconds; topology probe timeout is a duration.

[SessionCache]¶

Shared session cache logging and minimum pause (milliseconds). Debug frequency is a diagnostic event-count interval.

[SocketConfig]¶

Defaults for sockets. Buffers are bytes (-1 leaves OS defaults), timeouts are milliseconds, backlog is pending connections, and keepAlive is TCP keepalive rather than application connection pooling. Named socket sections override these values; see the complete named-option list below.

[SshPlugin]¶

SSH/SFTP listener and server identity. keyPairsDir stores host keys, banner is a file path and softwareVersion is the advertised server string. maxConcurrentSessions=0 means unlimited. hidden controls virtual-domain visibility.

[StoragePolicy]¶

Storage lifecycle worker. batchSize counts files, maxRelatedTransfers bounds related records and other timing settings are durations. enabled is opt-in; existing ENFORCE policies take effect when enabled. See the lifecycle policy guide before activation.

[StorageRepository]¶

Asynchronous persistence. *Size means storage-worker thread count, not queue capacity or batch size. *Delay, idle waits and ticket timeouts are milliseconds. *MaxAuthorisedSize caps repository entries (0 leaves the cap unset). Options only apply to repository types instantiated by this process.

[StreamPlug]¶

Shared stream-copy buffer size in bytes.

[TOTP]¶

OTP authentication provider configuration, including token endpoint, separate password/passcode client credentials, grant type and expected HTTP status. active=false disables this provider path; the login-form selector does not enable it.

[ThreadService]¶

Shared thread runtime. Virtual threads are opt-in; debugThreadLocal enables thread-local diagnostics.

[TransferScheduler]¶

Destination-dispatch concurrency and monitoring cache. poolSize=0 means unlimited destinations; queueSize is the pending-transfer fetch limit. delay is milliseconds, monitoringTimeout minutes and subscription frequency a duration.

[TransferServerProvider]¶

Mover-selection heuristics and usage updates. Update frequency is seconds; CV threshold and file-size penalty are dimensionless factors. Debug output helps inspect allocation decisions.

Named socket sections¶

SocketConfig.load reads the following keys from a component's named section. Common section names for this service are CallBack, RMIServerSocketFactory, RMIClientSocketFactory, ECpdsPlugin, FtpPlugin, FTPPassiveSocket, FTPActiveSocket, ProxySocket and ManagementEXEC; transfer/helper code can also use ECauthModule, FtpPASV, FtpPORT, FtpOPEN, HTTPSocketConfig, GCSSocketConfig, S3SocketConfig, WebDavModule, JSftp, TelnetWrapper and ECios. A transfer module or plugin must actually use that socket implementation for its settings to apply; Jetty HTTP listeners and third-party transfer clients do not automatically honour every low-level socket option.

Basic options inherit the values in [SocketConfig] shown above; the advanced TCP options from tcpCongestion onward default to unset and are read from the named section, not from the global [SocketConfig] defaults. Advanced options depend on OS/socket support. Caller-supplied addresses, ports and module/Host settings may override socket defaults.

Master-managed maps¶

These sections accept names determined by users, services or network addresses, so there is no finite list of key names:

Forced GeoIP entries are checked before database lookup. Local/private addresses otherwise skip GeoIP lookup; this does not prevent name resolution. See Live Earth monitoring.

FTP mapping and per-user families¶

Streaming filter executables must be installed on the machine executing them. Adding a definition does not apply it to every transfer; the current stream manager selects the named lbzip2 or zstd command when using that format.

Plugin and module families¶

[PluginList] is an open map of plugin names to definitions:

[PluginList]
name=implementation.Class@/path/to/plugin,option=value

The library path and per-plugin options depend on the plugin. Server plugins support maxConnections and inverseResolution; deleting or adding a plugin definition changes which services start. These are options inside the value, not new top-level ecmwf.properties groups. See Plugin Infrastructure.

[ECtrans] is an open family of global transfer-option defaults, with keys module.option (for example, ftp.passive). Its option set is defined by ECtransOptions and the selected module, not a fixed list of literal Cnf keys. Entity/transfer setup values can override these defaults. The complete option/default references are:

• ECtrans common options and the protocol pages under Transfer Modules.
• Host options, Destination options, Web User options and Data User options.

These entity options are not interchangeable with service sections. Some options are only meaningful for a particular module or execution role.