To query the status of all nodes in your cluster, complete the following steps.
curl --cookie cookies https://<IP-address-of-Central-Management-node>/api/cluster/status
The following is a sample response received.
For details of the meta object, see Message format.
{
"items": [
{
"key": "b35c54da-b556-4f91-ade5-d26283d68277",
"fqdn": "sps.example.com",
"health_status": null,
"sync_status": "n/a",
"meta": {
"configuration": "/api/cluster/nodes/b35c54da-b556-4f91-ade5-d26283d68277",
"href": "/api/cluster/status/b35c54da-b556-4f91-ade5-d26283d68277"
}
},
{
"key": "46f97a58-4028-467d-9a22-9cfe78ae3e1c",
"last_seen": "2018-02-08T10:00:30Z",
"fqdn": "managed-host.cluster",
"health_status": {
"memory": 62.5,
"disk": 1.9,
"swap": 0,
"load1": 0.53,
"load5": 0.68,
"load15": 0.37,
"sessions": {
"ssh": 3,
"rdp": 4
},
"total_sessions": 7
},
"sync_status": "pending",
"configuration_sync": {
"last_updated": "2018-02-08T09:59:00Z",
"last_checked": "2018-02-08T09:59:00Z",
"downloaded_xml_hash": "2853830f4aa0a90a63e75bab1b22e513",
"issues": {
"warnings": [
{
"message": "Connection 'simple_ssh_connection' and local service 'SSH' conflict on 10.30.42.42:22",
"paths": [
"/api/configuration/ssh/connections/12345",
"/api/configuration/local_services/ssh"
]
}
]
}
},
"meta": {
"configuration": "/api/cluster/nodes/46f97a58-4028-467d-9a22-9cfe78ae3e1c",
"href": "/api/cluster/status/46f97a58-4028-467d-9a22-9cfe78ae3e1c"
}
}
],
"meta": {
"href": "/api/cluster/status",
"parent": "/api/cluster",
"self": "/api/cluster/status/b35c54da-b556-4f91-ade5-d26283d68277"
}
}
| Elements | Type | Description | ||
|---|---|---|---|---|
| items | Top-level element (list of JSON objects) | List of endpoints (objects) available from the current endpoint. | ||
| key | string | The ID of the node. | ||
|
|
fqdn |
|
string |
The address of the node as a fully qualified domain name. |
|
|
health_status |
|
null or object |
The health status of a node. If the node is down, the value is null. Otherwise, the health-related data is listed. |
| memory | floating point integer (percent) | Memory use | ||
| disk | floating point integer (percent) | Hard disk use | ||
| swap | floating point integer (percent) | Swap use | ||
| load1 | floating point integer |
The average system load during the last one minute. The values mean the following:
| ||
| load5 | floating point integer |
The average system load during the last five-minute period. The values mean the following:
| ||
| load15 | floating point integer |
The average system load during the last fifteen-minute period. The values mean the following:
| ||
| sessions | string |
The protocol type and the number of ongoing sessions. For example: "sessions": {
"ssh": 3,
"rdp": 4
}, | ||
| total_sessions | integer (number of) | The total number of ongoing sessions. | ||
| sync_status | string |
Indicates the status of configuration synchronization. It has the following values:
| ||
| meta | Top-level item (JSON object) | Contains links to different parts of the REST service. | ||
| configuration | string (relative path) | The path to the configuration of the node that returned the response. | ||
| href | string (relative path) | The path to the node that returned the response. | ||
| last_seen | string | The last time the node sent status information to the Central Management node, in ISO 8601 format. | ||
| configuration_sync | Top-level item (JSON object) | |||
|
|
|
downloaded_xml_hash |
string |
The hash of the latest downloaded configuration file (used for configuration synchronization). If no configuration file has been downloaded yet, it says null. |
| last_updated | string | The last time the node's configuration was synchronized, in ISO 8601 format. | ||
| last_checked | string | The last time the node attempted to fetch a new configuration, in ISO 8601 format. | ||
| issues | Top-level item (JSON object) | The issues that occurred during configuration synchronization. | ||
To query the status of one particular node in your cluster, complete the following steps.
curl --cookie cookies https://<IP-address-of-Central-Management-node>/api/cluster/status/<node-id-of-node-to-be-queried>
The following is a sample response received.
For details of the meta object, see Message format.
For details of the other objects, see tables Cluster status details and "issues" object details.
{
"fqdn": "managed-host.cluster",
"key": "46f97a58-4028-467d-9a22-9cfe78ae3e1c",
"configuration_sync": {
"downloaded_xml_hash": "2853830f4aa0a90a63e75bab1b22e513",
"last_updated": "2018-02-08T09:59:30Z",
"last_checked": "2018-02-08T09:59:30Z",
"issues": {}
},
"health_status": {
"memory": 62.5,
"disk": 1.9,
"swap": 0,
"load1": 0.53,
"load5": 0.68,
"load15": 0.37,
"sessions": {
"ssh": 3,
"rdp": 4
},
"total_sessions": 7
},
"sync_status": "up-to-date",
"last_seen": "2018-02-08T10:00:00Z",
"meta": {
"configuration": "/api/cluster/nodes/46f97a58-4028-467d-9a22-9cfe78ae3e1c",
"href": "/api/cluster/status/46f97a58-4028-467d-9a22-9cfe78ae3e1c"
}
}
| Elements | Type | Description | ||
|---|---|---|---|---|
| items | Top-level element (list of JSON objects) | List of endpoints (objects) available from the current endpoint. | ||
| key | string | The ID of the node. | ||
|
|
fqdn |
|
string |
The address of the node as a fully qualified domain name. |
|
|
health_status |
|
null or object |
The health status of a node. If the node is down, the value is null. Otherwise, the health-related data is listed. |
| memory | floating point integer (percent) | Memory use | ||
| disk | floating point integer (percent) | Hard disk use | ||
| swap | floating point integer (percent) | Swap use | ||
| load1 | floating point integer |
The average system load during the last one minute. The values mean the following:
| ||
| load5 | floating point integer |
The average system load during the last five-minute period. The values mean the following:
| ||
| load15 | floating point integer |
The average system load during the last fifteen-minute period. The values mean the following:
| ||
| sessions | string |
The protocol type and the number of ongoing sessions. For example: "sessions": {
"ssh": 3,
"rdp": 4
}, | ||
| total_sessions | integer (number of) | The total number of ongoing sessions. | ||
| sync_status | string |
Indicates the status of configuration synchronization. It has the following values:
| ||
| meta | Top-level item (JSON object) | Contains links to different parts of the REST service. | ||
| configuration | string (relative path) | The path to the configuration of the node that returned the response. | ||
| href | string (relative path) | The path to the node that returned the response. | ||
| last_seen | string | The last time the node sent status information to the Central Management node, in ISO 8601 format. | ||
| configuration_sync | Top-level item (JSON object) | |||
|
|
|
downloaded_xml_hash |
string |
The hash of the latest downloaded configuration file (used for configuration synchronization). If no configuration file has been downloaded yet, it says null. |
| last_updated | string | The last time the node's configuration was synchronized, in ISO 8601 format. | ||
| last_checked | string | The last time the node attempted to fetch a new configuration, in ISO 8601 format. | ||
| issues | Top-level item (JSON object) | The issues that occurred during configuration synchronization. | ||
Nodes fetch their configuration from the Central management node, and merge it into their own configuration. Depending on their role, nodes may merge the whole configuration into their own (Managed host nodes), or only the cluster-specific parts (nodes with no roles assigned). Whenever a configuration change is made on the Central management node and the change is committed, it is synchronized to all nodes in the cluster as soon as the nodes fetch the latest configuration from the Central management node.
When synchronizing the central configuration across nodes, you may want to:
Keep certain parts in the configuration of individual nodes unchanged.
Customize certain parts of the central configuration to specific needs of individual nodes in the cluster (for example, your nodes may access external services through different network addresses).
You can achieve all of these by using a configuration synchronization plugin that contains transformations for the problematic parts. The plugin only runs on nodes that have the Managed host role.
Customizing certain parts or features of a node using a configuration synchronization plugin has the same limitations as configuring Safeguard for Privileged Sessions (SPS) through the REST API. In other words, whatever you can configure through the REST API, you can configure the exact same settings using the plugin. One notable difference between the REST API and the plugin is that using the REST API, you can only read certain types of data (such as keys and passwords), while using the configuration synchronization plugin, you can write these types of data as well.
Data structures in the plugin are represented as nested JSON objects. For object references, the plugin uses keys.
The plugin works with the following key parameters:
For example, an RDP connection policy on a Managed host node specifies the following client and target addresses:
$ curl ... https://<url-of-Central-Management-node>/api/configuration/rdp/connections/<id-of-the-connection-policy>
{
"body": {
"network": {
"clients": [
"0.0.0.0/0"
],
"ports": [
3389
],
"targets": [
"10.30.255.28/24"
]
},
},
...
}
In the following example, an RDP connection policy is configured with the following details on the Central management node:
$ curl ... https://<url-of-Managed-Node>/api/configuration/rdp/connections/<id-of-the-connection-policy>
{
"body": {
"network": {
"clients": [
"0.0.0.0/0"
],
"ports": [
3389
],
"targets": [
"10.30.255.8/24"
]
},
},
...
}
To ensure that the details of the connection policy on the Managed host node are kept as-is after configuration synchronization, add the following lines to the plugin main.py file:
$ cat main.py
def merge(local_config: dict, merged_config: dict, node_id: str, plugin_config: str, **kwargs):
merged_config['rdp']['connections'][<id-of-the-connection-policy>]['network']['targets'][0] = "10.30.255.8/24"
return merged_config
Due to possible new (as yet undefined) parameters, it is good practice to close the parameter list of the merge function with **kwargs.
In case you need assistance with writing customized transformations, contact our Professional Services Team, and a One Identity Service Delivery Engineer will be able to help you.
NOTE: Configuration settings related to networking (/api/configuration/network), local services (/api/configuration/local_services), and the management of SPS (/api/configuration/management) are not overwritten on the nodes by configuration synchronization even when not using a plugin.
To upload a configuration synchronization plugin to the Central Management node, complete the following steps.
For details, see Open a transaction.
POST the plugin as a zip file (application/zip) to the https://<IP-address-of-Central-Management-node>/api/upload/plugins endpoint, for example:
curl -X POST -H "Content-Type: application/zip" --cookie cookies https://<IP-address-of-Central-Management-node>/api/upload/plugins --data-binary @<path-to-plugin.zip>
The following is a sample response received.
For details of the meta object, see Message format.
{
"body": {
"api": "1.0",
"default_configuration": "",
"description": "Whitelist the list of paths when merging the configuration",
"name": "whitelist",
"path": "/opt/scb/var/plugins/configuration_sync/whitelist",
"scb_max_version": "",
"scb_min_version": "",
"version": "1.0"
},
"key": "794a5e17-b8be-4426-8596-0dfc129c06ef",
"meta": {
"href": "/api/configuration/plugins/configuration_sync/794a5e17-b8be-4426-8596-0dfc129c06ef",
"parent": "/api/configuration/plugins/configuration_sync",
"remaining_seconds": 599
}
}
| Elements | Type | Description | |
|---|---|---|---|
| body | Top-level element (JSON object) | ||
| api | string | Always "1.0". | |
| default_configuration | string | Contains the default configuration of the plugin if there is one. | |
| description | string | The description of what the plugin does. | |
| name | string | The name of the plugin. | |
| path | string | The path to the plugin. | |
| scb_max_version | string | The plugin is compatible with SPS versions not later than this one. | |
| scb_min_version | string | The plugin is compatible with SPS versions not earlier than this one. | |
| version | string | The version number of the plugin. | |
| key | string | The ID of the plugin. | |
Replace /api/cluster/configuration_sync_plugin with:
{
"enabled": true,
"plugin": "<'key' from-response-of-last-creation>",
"configuration": ""
}
For example:
curl -X POST -H "Content-Type: application/json" --cookie cookies https://<IP-address-of-Central-Management-node>/api/cluster/configuration_sync_plugin --data '{"enabled": true, "plugin": "794a5e17-b8be-4426-8596-0dfc129c06ef", "configuration": ""}'
The following is a sample response received:
{
"plugin": {
"key": "794a5e17-b8be-4426-8596-0dfc129c06ef",
"meta": {
"href": "/api/configuration/plugins/configuration_sync/794a5e17-b8be-4426-8596-0dfc129c06ef"
}
}
}
For details, see Commit a transaction.
To disable a configuration synchronization plugin on the Central Management node, complete the following steps.
For details, see Open a transaction.
{
"enabled": false
}
For example:
curl -X POST -H "Content-Type: application/json" --cookie cookies https://<IP-address-of-Central-Management-node>/api/cluster/configuration_sync_plugin --data '{"enabled": false}'
The following is a sample response received:
{
"plugin": {
"key": null,
"meta": {}
}
}
For details, see Commit a transaction.
© ALL RIGHTS RESERVED. 使用条款 隐私 Cookie Preference Center