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 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 |
|
POST |
Creates a new instance of an object when used with a relation parent path, such as |
|
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 |
|
PATCH |
Updates the attributes of an existing object when used with a path representing an object, such as |
|
DELETE |
Deletes an existing object when used with a path representing an object, such as |
|
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:
{
"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):
{
"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:{ "op" : "replace", "path" : "description", "value" : "A new backend." }
is analogous to:
$ 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:{ "op" : "add", "path" : "jeProperty", "value" : "je.env.backgroundReadLimit=0" }
is analogous to:
$ 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:{ "op" : "remove", "path" : "[jeProperty eq \"je.cleaner.adjustUtilization=false\"]" }
is analogous to:
$ 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 isvalue
:{ "op" : "remove", "path" : "jeProperty[value eq \"je.nodeMaxEntries=32\"]" }
is analogous to:
$ 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:
{ "op" : "remove", "path" : "id2childrenIndexEntryLimit" }
is analogous to:
$ 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:
{
"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."
}
]
}
}