Skip to content

Control API timeouts

Clients can interact with the Control process through a rich public API. While this allows client processes to query the state of Control effectively, it also introduces potential vulnerabilities. Long-running client requests block Control from proceeding with its other tasks, potentially exceeding the heartbeat timeout and triggering a failover. To reduce this risk, system administrators can configure timeout values for Control’s public APIs, helping to safeguard the system against such scenarios.

Enabling the feature

Although using API timeouts is recommended, the feature is disabled by default to ensure backward compatibility with the Platform. To enable the feature before installation, add DELTACONTROL_API_TIMEOUT=YES to the install.config file.

Alternatively, you can enable it post-installation by updating the delta.profile file with export DELTACONTROL_API_TIMEOUT=YES.

This change must be applied across all servers, and it only takes effect after restarting the Control process. There is no option to toggle the feature in a running environment.

Once enabled, the feature sets a default timeout of 30 seconds. This default cannot be configured during installation but can be modified later in the Control UI, as described in the next section.

Configuring timeouts

Timeouts are managed through the DC_API_TIMEOUTS configuration parameter. Key points:

  • Only the DEFAULT parameter is considered; overrides are ignored.
  • Timeouts can be specified for any non-state-changing (read) API of Control by adding an entry to the configuration parameter. Timeouts don't apply to state-changing (write) API requests.
  • Timeouts are not user-group specific. If a timeout is configured on a non state changing API, it applies to all non-Administrator user requests. Administrator requests don't get timed out.
  • The feature defines a default timeout value of 30 seconds. This applies to all time-restrictable APIs for which an explicit timeout value isn't set. The default timeout value is listed in the dedicated configuration parameter. It is not possible to omit the DEFAULT entry from the parameter.
  • To disable the timeout for a specific API, set the API's timeout value to 0 in the configuration parameter.
  • It is recommended that API timeouts be shorter than Control's corresponding heartbeat timeout, to ensure the feature effectively prevents failovers.

Developing custom Control APIs

When working with custom Control APIs:

  • During the execution of a time-restricted API, the value of .z.w will be 0i. Use .pm.w[] to retrieve the client handle when developing custom control APIs.
  • You can use .pm.exas inside a Control API to invoke another Control API, with the following constraints:
    • A state changing API can't be invoked using .pm.exas from inside a time-restricted API.
    • The timeout of a time-restricted API isn't considered in case it is invoked via .pm.exas from inside another time-restricted API. I.e., the outer-most API's timeout value applies to the whole request.