Configure API rate limits

Set rate limits that are appropriate for your Deep Security Manager environment. Your limits need to allow expected API usage while protecting against accidental or malicious over-use. You can disable the API rate limiter if desired.

Rate limits are applied to the following entities:

  • User: The number of API calls that the manager can receive from an API key per minute.
  • Tenant: The number of calls that a tenant (including the primary tenant) can receive per minute. This limit effectively sets a collective limit on all API keys that have been created on a tenant. For example, if users are limited to 300 calls per minute and tenants are limited to 1000 calls per minute, the total calls from 4 API keys could reach the tenant limit without exceeding the user limit.
  • Manager node: The number of calls a manager node can receive per minute. This limit effectively sets a collective limit on calls made to all tenants on a single instance of Deep Security Manager. Multiple tenants can collectively exceed their node's rate limit without any of them having exceeded the tenant limit.

The limits apply to each user, tenant, and node. You cannot set a different limit for an individual entity.

Determine suitable rate limits

The rate limits that you use for your Deep Security Manager instances depend on the available resources of your manager computer and the API traffic that they receive. The following rate limits are set by default:

  • User: 500
  • Tenant: 1000
  • Node: 5000

To determine whether your current rate limits are suitable for your environment, observe the behavior of your scripts and the computer of the manager instance that they are calling:

  • Raise the limits if your scripts often exceed the limits and manager resources are not highly impacted.
  • Lower the limits if you observe periods of high resource usage on the manager computer when spikes in API calls occur.

You can use the APIUsageAPI class of an SDK to determine call rates. (See API Usage in the API Reference.) For example you can search for all API calls that occur during a certain time period. Parse the returned data to count the total calls. You can also find the number of code 429 responses. (See Date-range searches.)

Tip:

API calls are not the only sources of stress on manager resources. You need to correlate high API call rates with increases in resource usage on your manager computer.

Set the rate limits

Use the dsm_c command of the Deep Security Manager CLI to set rate limits. You can also disable and enable the rate limiter. When disabled, rate limiting is not enforced and the rate limits that are set are not effective.

The following table lists the setting names that you can use with the changesetting and viewsetting actions of the command.

Property Setting name Possible values
API rate limiter status com.trendmicro.ds.api:settings.configuration.apiRateLimiterEnabled true or false
User limit com.trendmicro.ds.api:settings.configuration.apiRateLimiterUserLimit Any integer. for example, 500 sets the limit to 500 calls/minute. A negative number allows unlimited calls.
Tenant limit com.trendmicro.ds.api:settings.configuration.apiRateLimiterTenantLimit Any integer. for example, 1000 sets the limit to 500 calls/minute. A negative number allows unlimited calls.
Node limit com.trendmicro.ds.api:settings.configuration.apiRateLimiterNodeLimit Any integer. for example, 500 sets the limit to 500 calls/minute. A negative number allows unlimited calls.

The viewsetting action uses the following syntax: dsm_c -action viewsetting -name *setting_name*

The following example displays the status of the rate limiting feature status:

dsm_c -action viewsetting -name com.trendmicro.ds.api:settings.configuration.apiRateLimiterEnabled

The changesetting command uses the following syntax: dsm_c -action changesetting -name *setting_name* -value *setting_value*

The following example changes the user limit to 1000:

dsm_c -action changesetting -name com.trendmicro.ds.api:settings.configuration.apiRateLimiterUserLimit -value 1000

For information about the dsm_c command, see Command-line basics in the Deep Security Help Center.

Disable rate limiting for a tenant account

If you have multi-tenancy enabled, you can use the Deep Security Manager web page to disable the API rate limiter for specific tenants.

  1. In the Deep Security Manager console, click Administration > Tenants.
  2. Open the properties for the tenant.
  3. On the Features tab, in the Disable Features area, select API Rate Limiter.
  4. Click OK.