--- title: "Relationship between the Configuration API and the dsconfig tool" description: Describes how the Configuration API mirrors the dsconfig tool, mapping hyphen-case property names to camel-case attributes. component: pingdirectory version: 10.2 page_id: pingdirectory:pingdatasync_server_administration_guide:pd_sync_rel_config_api_dsconfig_tool canonical_url: https://docs.pingidentity.com/pingdirectory/11.1/pingdirectory_server_administration_guide/pd_ds_config_api_dsconfig_tool_rel.html llms_txt: https://docs.pingidentity.com/pingdirectory/llms.txt docs_for_agents: https://developer.pingidentity.com/build-with-ai/docs-for-agents.md revdate: 2023-09-13T00:00:00Z section_ids: get-example: GET Example get-list-example: GET list example patch-example: PATCH Example --- # Relationship between the Configuration API and the `dsconfig` tool The Configuration API is designed to mirror the `dsconfig` tool, using the same names for properties and object types. 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 is not important. Therefore, `baseDN` is the same as `baseDn`. Object types are represented in hyphen case. API paths mirror what is 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 DB 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 SCIM specification. Specific attributes can be requested using the `attributes` query parameter, whose value must be a comma-delimited list of properties to be returned, for example `attributes=baseDN,description`. Likewise, attributes can be excluded from responses by specifying the `excludedAttributes` parameter. See [Sorting and filtering configuration objects](pd_sync_sort_filter_config_objects.html) for more information on query parameters. Operations supported by the API are those typically found in REST APIs: | HTTP Method | Description | Related dsconfig Example | | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------- | | GET | Lists the attributes 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 attributes of an object. A PUT operation is similar to a PATCH operation, except that the PATCH is determined by determining the difference between an existing target object and a supplied source object. Only those attributes 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 attributes 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` | The OPTIONS method can also be used to determine the operations permitted for a particular path. Object names, such as `userRoot` in the Description column, must be URL-encoded in the `path` segment of a URL. For example, `%20` must be used in place of spaces, and `%25` is used in place of the percent (%) character. So the URL for accessing the HTTP Connection Handler object is: ``` /config/connection-handlers/http%20connection%20handler ``` ## GET Example The following is a sample GET request for information about the `userRoot` backend: ``` GET /config/backends/userRoot Host: example.com:5033 Accept: application/scim+json ``` The response: ```json { "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 is a sample GET request for all local backends: ``` GET /config/backends Host: example.com:5033 Accept: application/scim+json ``` The response (which has been shortened): ```json { "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=admin data" ], "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 Configuration can be modified using the HTTP PATCH method. 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, used to indicate the configuration attribute to modify. The configuration object's attributes can be modified in the following ways. These operations are analogous to the `dsconfig modify-[object]` options. * An operation to set the single-valued `description` attribute to a new value: ```json { "op" : "replace", "path" : "description", "value" : "A new backend." } ``` is analogous to: ```shell $ dsconfig set-backend-prop --backend-name userRoot \ --set "description:A new backend" ``` * An operation to add a new value to the multi-valued `jeProperty` attribute: ```json { "op" : "add", "path" : "jeProperty", "value" : "je.env.backgroundReadLimit=0" } ``` is analogous to: ```shell $ dsconfig set-backend-prop --backend-name userRoot \ --add je-property:je.env.backgroundReadLimit=0 ``` * An operation to remove a value from a multi-valued property. In this case, `path` specifies a SCIM filter identifying the value to remove: ```json { "op" : "remove", "path" : "[jeProperty eq \"je.cleaner.adjustUtilization=false\"]" } ``` is analogous to: ```shell $ dsconfig set-backend-prop --backend-name userRoot \ --remove je-property:je.cleaner.adjustUtilization=false ``` * A 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 `value`: ```json { "op" : "remove", "path" : "jeProperty[value eq \"je.nodeMaxEntries=32\"]" } ``` is analogous to: ```shell $ dsconfig set-backend-prop --backend-name userRoot \ --remove je-property:je.nodeMaxEntries=32 ``` * An 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: ```json { "op" : "remove", "path" : "id2childrenIndexEntryLimit" } ``` is analogous to: ```shell $ dsconfig set-backend-prop --backend-name userRoot \ --reset id2childrenIndexEntryLimit ``` The following is the full example request. The API responds with the entire modified configuration object, which can include a SCIM extension attribute `urn:unboundid:schemas:configuration:messages` containing additional instructions: Example 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" } ] } ``` Example response: ```json { "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." } ] } } ```