PingDirectory

The Configuration API and dsconfig

The Configuration API is designed to mirror the dsconfig tool, using the same names for properties and object types. The following formatting conventions apply to these names:

  • Property names are presented as hyphen case in dsconfig and as camel-case attributes in the API.

    • In API requests that specify property names, case isn’t important. baseDN is the same as baseDn.

  • Object types are represented in hyphen case.

  • API paths mirror what’s in dsconfig. For example, the dsconfig list-connection-handlers command is analogous to the API’s /config/connection-handlers path.

  • Object types that appear in the schema URNs adhere to a type:subtype syntax. For example, a local database backend’s schema URN is urn:unboundid:schemas:configuration:2.0:backend:local-db.

Like the dsconfig tool, all configuration updates made through the API are recorded in logs/config-audit.log.

The API includes the filter, sort, and pagination query parameters described by the System for Cross-domain Identity Management (SCIM) specification. Request specific attributes using the attributes query parameter, whose value must be a comma-delimited list of properties to be returned, such as attributes=baseDN,description. You can exclude attributes from responses by specifying the excludedAttributes parameter. Learn more about query parameters in Sort and filter objects.

The Configuration API supports the HTTP methods described in the following table. Each method operates on configuration objects identified by paths under the /config endpoint. You can also use the OPTIONS method to determine the operations permitted for a particular path.

Configuration API operations supported in REST APIs
HTTP method Description Related dsconfig example

GET

Lists the properties of an object when used with a path representing an object, such as /config/global-configuration or /config/backends/userRoot.

Can also list objects when used with a path representing a parent relation, such as /config/backends.

  • get-backend-prop

  • list-backends

  • get-global-configuration-prop

POST

Creates a new instance of an object when used with a relation parent path, such as /config/backends.

create-backend

PUT

Replaces the existing properties of an object. A PUT operation is similar to a PATCH operation, except that the PATCH identifies the difference between an existing target object and a supplied source object. Only those properties in the source object are modified in the target object. The target object is specified using a path, such as /config/backends/userRoot.

  • set-backend-prop

  • set-global-configuration-prop

PATCH

Updates the properties of an existing object when used with a path representing an object, such as /config/backends/userRoot.

  • set-backend-prop

  • set-global-configuration-prop

DELETE

Deletes an existing object when used with a path representing an object, such as /config/backends/userRoot.

delete-backend

Object names, such as the HTTP Connection Handler, must be URL-encoded for use in the path segment of a URL. For example, %20 must be used in place of spaces and %25 in place of the percent character.

For example, the following URL is encoded to access the HTTP Connection Handler object:

/config/connection-handlers/http%20connection%20handler

GET example

The following code examples demonstrate a GET request for information about the userRoot backend and the API’s response:

GET request 
GET /config/backends/userRoot
Host: example.com:5033
Accept: application/scim+json
GET response 
{
  "schemas": [
    "urn:unboundid:schemas:configuration:2.0:backend:local-db"
  ],
   "id": "userRoot",
   "meta": {
     "resourceType": "Local DB Backend",
     "location": "http://localhost:5033/config/backends/userRoot"
   },
   "backendID": "userRoot2",
   "backgroundPrime": "false",
   "backupFilePermissions": "700",
   "baseDN": [
     "dc=example2,dc=com"
   ],
   "checkpointOnCloseCount": "2",
   "cleanerThreadWaitTime": "120000",
   "compressEntries": "false",
   "continuePrimeAfterCacheFull": "false",
   "dbBackgroundSyncInterval": "1 s",
   "dbCachePercent": "10",
   "dbCacheSize": "0 b",
   "dbCheckpointerBytesInterval": "20 mb",
   "dbCheckpointerHighPriority": "false",
   "dbCheckpointerWakeupInterval": "1 m",
   "dbCleanOnExplicitGC": "false",
   "dbCleanerMinUtilization": "75",
   "dbCompactKeyPrefixes": "true",
   "dbDirectory": "db",
   "dbDirectoryPermissions": "700",
   "dbEvictorCriticalPercentage": "0",
   "dbEvictorLruOnly": "false",
   "dbEvictorNodesPerScan": "10",
   "dbFileCacheSize": "1000",
   "dbImportCachePercent": "60",
   "dbLogFileMax": "50 mb",
   "dbLoggingFileHandlerOn": "true",
   "dbLoggingLevel": "CONFIG",
   "dbNumCleanerThreads": "0",
   "dbNumLockTables": "0",
   "dbRunCleaner": "true",
   "dbTxnNoSync": "false",
   "dbTxnWriteNoSync": "true",
   "dbUseThreadLocalHandles": "true",
   "deadlockRetryLimit": "10",
   "defaultCacheMode": "cache-keys-and-values",
   "defaultTxnMaxLockTimeout": "10 s",
   "defaultTxnMinLockTimeout": "10 s",
   "enabled": "false",
   "explodedIndexEntryThreshold": "4000",
   "exportThreadCount": "0",
   "externalTxnDefaultBackendLockBehavior": "acquire-before-retries",
   "externalTxnDefaultMaxLockTimeout": "100 ms",
   "externalTxnDefaultMinLockTimeout": "100 ms",
   "externalTxnDefaultRetryAttempts": "2",
   "hashEntries": "false",
   "id2childrenIndexEntryLimit": "66",
   "importTempDirectory": "import-tmp",
   "importThreadCount": "16",
   "indexEntryLimit": "4000",
   "isPrivateBackend": "false",
   "javaClass": "com.unboundid.directory.server.backends.jeb.BackendImpl",
   "jeProperty": [
     "je.cleaner.adjustUtilization=false",
     "je.nodeMaxEntries=32"
   ],
   "numRecentChanges": "50000",
   "offlineProcessDatabaseOpenTimeout": "1 h",
   "primeAllIndexes": "true",
   "primeMethod": [
     "none"
   ],
   "primeThreadCount": "2",
   "primeTimeLimit": "0 ms",
   "processFiltersWithUndefinedAttributeTypes": "false",
   "returnUnavailableForUntrustedIndex": "true",
   "returnUnavailableWhenDisabled": "true",
   "setDegradedAlertForUntrustedIndex": "true",
   "setDegradedAlertWhenDisabled": "true",
   "subtreeDeleteBatchSize": "5000",
   "subtreeDeleteSizeLimit": "5000",
   "uncachedId2entryCacheMode": "cache-keys-only",
   "writabilityMode": "enabled"
}

GET list example

The following code examples demonstrate a GET request for a list of all local backends and a truncated version of the API’s response:

GET request 
GET /config/backends/
Host: example.com:5033
Accept: application/scim+json
GET response 
{
  "schemas": [
    "urn:ietf:params:scim:api:messages:2.0:ListResponse"
  ],
  "totalResults": 24,
  "Resources": [
    {
      "schemas": [
        "urn:unboundid:schemas:configuration:2.0:backend:ldif"
      ],
      "id": "adminRoot",
      "meta": {
        "resourceType": "LDIF Backend",
        "location": "http://localhost:5033/config/backends/adminRoot"
      },
      "backendID": "adminRoot",
      "backupFilePermissions": "700",
      "baseDN": [
        "cn=topology,cn=config"
      ],
      "enabled": "true",
      "isPrivateBackend": "true",
      "javaClass": "com.unboundid.directory.server.backends.LDIFBackend",
      "ldifFile": "config/admin-backend.ldif",
      "returnUnavailableWhenDisabled": "true",
      "setDegradedAlertWhenDisabled": "false",
      "writabilityMode": "enabled"
    },
    {
      "schemas": [
        "urn:unboundid:schemas:configuration:2.0:backend:trust-store"
      ],
      "id": "ads-truststore",
      "meta": {
        "resourceType": "Trust Store Backend",
        "location": "http://localhost:5033/config/backends/ads-truststore"
      },
      "backendID": "ads-truststore",
      "backupFilePermissions": "700",
      "baseDN": [
        "cn=ads-truststore"
      ],
      "enabled": "true",
      "javaClass": "com.unboundid.directory.server.backends.TrustStoreBackend",
      "returnUnavailableWhenDisabled": "true",
      "setDegradedAlertWhenDisabled": "true",
      "trustStoreFile": "config/server.keystore",
      "trustStorePin": "**",
      "trustStoreType": "JKS",
      "writabilityMode": "enabled"
    },
    {
      "schemas": [
        "urn:unboundid:schemas:configuration:2.0:backend:alarm"
      ],
      "id": "alarms",
      "meta": {
        "resourceType": "Alarm Backend",
        "location": "http://localhost:5033/config/backends/alarms"
      },
  ...

PATCH example

The PATCH request body is a JSON object formatted according to the SCIM PATCH request. The Configuration API supports a subset of possible values for the path attribute that indicates the configuration attribute to modify.

You can modify the configuration object’s attributes according to the information in the following table, which also provides the comparable dsconfig option for each PATCH request:

Table of PATCH request operations
Operation PATCH request Comparable dsconfig option

Set the single-valued description attribute to a new value.

 
{
  "op" : "replace",
  "path" : "description",
  "value" : "A new backend."
}
 
$ dsconfig set-backend-prop
  --backend-name userRoot \
  --set "description:A new backend"

Add a new value to the multi-valued jeProperty attribute.

 
{
  "op" : "add",
  "path" : "jeProperty",
  "value" : "je.env.backgroundReadLimit=0"
}
 
$ dsconfig  set-backend-prop --backend-name userRoot \
  --add je-property:je.env.backgroundReadLimit=0

Remove a value from a multi-valued property. In this case, path specifies a SCIM filter identifying the value to remove.

 
{
  "op" : "remove",
  "path" : "[jeProperty eq \"je.cleaner.adjustUtilization=false\"]"
}
 
$ dsconfig set-backend-prop --backend-name userRoot \
  --remove je-property:je.cleaner.adjustUtilization=false

Second operation to remove a value from a multi-valued property, where the path specifies both an attribute to modify and a SCIM filter whose attribute is the following value.

 
{
  "op" : "remove",
  "path" : "jeProperty[value eq \"je.nodeMaxEntries=32\"]"
}
 
$ dsconfig set-backend-prop --backend-name userRoot \
  --remove je-property:je.nodeMaxEntries=32

Option to remove one or more values of a multi-valued attribute. This has the effect of restoring the attribute’s value to its default value.

 
{
  "op" : "remove",
  "path" : "id2childrenIndexEntryLimit"
}
 
$ dsconfig set-backend-prop --backend-name userRoot \
  --reset id2childrenIndexEntryLimit

The following code examples demonstrate a full PATCH request and response. The API responds with the entire modified configuration object, which can include the SCIM extension attribute urn:unboundid:schemas:configuration:messages containing additional instructions.

PATCH request 
PATCH /config/backends/userRoot
Host: example.com:5033
Accept: application/scim+json

{
  "schemas" : [ "urn:ietf:params:scim:api:messages:2.0:PatchOp" ],
  "Operations" : [ {
    "op" : "replace",
    "path" : "description",
    "value" : "A new backend."
  }, {
    "op" : "add",
    "path" : "jeProperty",
    "value" : "je.env.backgroundReadLimit=0"
  }, {
    "op" : "remove",
    "path" : "[jeProperty eq \"je.cleaner.adjustUtilization=false\"]"
  }, {
    "op" : "remove",
    "path" : "jeProperty[value eq \"je.nodeMaxEntries=32\"]"
  }, {
    "op" : "remove",
    "path" : "id2childrenIndexEntryLimit"
  } ]
}
PATCH response 
{
 "schemas": [
   "urn:unboundid:schemas:configuration:2.0:backend:local-db"
 ],
 "id": "userRoot2",
 "meta": {
   "resourceType": "Local DB Backend",
   "location": "http://example.com:5033/config/backends/userRoot2"
 },
 "backendID": "userRoot2",
 "backgroundPrime": "false",
 "backupFilePermissions": "700",
 "baseDN": [
   "dc=example2,dc=com"
 ],
 "checkpointOnCloseCount": "2",
 "cleanerThreadWaitTime": "120000",
 "compressEntries": "false",
 "continuePrimeAfterCacheFull": "false",
 "dbBackgroundSyncInterval": "1 s",
 "dbCachePercent": "10",
 "dbCacheSize": "0 b",
 "dbCheckpointerBytesInterval": "20 mb",
 "dbCheckpointerHighPriority": "false",
 "dbCheckpointerWakeupInterval": "1 m",
 "dbCleanOnExplicitGC": "false",
 "dbCleanerMinUtilization": "75",
 "dbCompactKeyPrefixes": "true",
 "dbDirectory": "db",
 "dbDirectoryPermissions": "700",
 "dbEvictorCriticalPercentage": "0",
 "dbEvictorLruOnly": "false",
 "dbEvictorNodesPerScan": "10",
 "dbFileCacheSize": "1000",
 "dbImportCachePercent": "60",
 "dbLogFileMax": "50 mb",
 "dbLoggingFileHandlerOn": "true",
 "dbLoggingLevel": "CONFIG",
 "dbNumCleanerThreads": "0",
 "dbNumLockTables": "0",
 "dbRunCleaner": "true",
 "dbTxnNoSync": "false",
 "dbTxnWriteNoSync": "true",
 "dbUseThreadLocalHandles": "true",
 "deadlockRetryLimit": "10",
 "defaultCacheMode": "cache-keys-and-values",
 "defaultTxnMaxLockTimeout": "10 s",
 "defaultTxnMinLockTimeout": "10 s",
 "description": "123",  "enabled": "false",
 "explodedIndexEntryThreshold": "4000",
 "exportThreadCount": "0",
 "externalTxnDefaultBackendLockBehavior": "acquire-before-retries",
 "externalTxnDefaultMaxLockTimeout": "100 ms",
 "externalTxnDefaultMinLockTimeout": "100 ms",
 "externalTxnDefaultRetryAttempts": "2",
 "hashEntries": "false",
 "importTempDirectory": "import-tmp",
 "importThreadCount": "16",
 "indexEntryLimit": "4000",
 "isPrivateBackend": "false",
 "javaClass": "com.unboundid.directory.server.backends.jeb.BackendImpl",
 "jeProperty": [  "\"je.env.backgroundReadLimit=0\""
 ],
 "numRecentChanges": "50000",
 "offlineProcessDatabaseOpenTimeout": "1 h",
 "primeAllIndexes": "true",
 "primeMethod": [
   "none"
 ],
 "primeThreadCount": "2",
 "primeTimeLimit": "0 ms",
 "processFiltersWithUndefinedAttributeTypes": "false",
 "returnUnavailableForUntrustedIndex": "true",
 "returnUnavailableWhenDisabled": "true",
 "setDegradedAlertForUntrustedIndex": "true",
 "setDegradedAlertWhenDisabled": "true",
 "subtreeDeleteBatchSize": "5000",
 "subtreeDeleteSizeLimit": "5000",
 "uncachedId2entryCacheMode": "cache-keys-only",
 "writabilityMode": "enabled",
 "urn:unboundid:schemas:configuration:messages:2.0": {
   "requiredActions": [
     {
       "property": "jeProperty",
       "type": "componentRestart",
       "synopsis": "In order for this modification to take effect,
          the component must be restarted, either by disabling and
          re-enabling it, or by restarting the server"
     },
     {
       "property": "id2childrenIndexEntryLimit",
       "type": "other",
       "synopsis": "If this limit is increased, then the contents
          of the backend must be exported to LDIF and re-imported to
          allow the new limit to be used for any id2children keys
          that had already hit the previous limit."
     }
   ]
 }
}