Monitor appliance health status
To monitor the health status of an appliance, query the /api/health-status endpoint.
curl --cookie cookies https://<IP-address-of-SPS>/api/health-status
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.
{
"health_status": {
"cpu": 5.4,
"disk": 10.3,
"load1": 1.93,
"load15": 1.98,
"load5": 2.01,
"memory": 46.3,
"sessions": {
"http": 0,
"ica": 0,
"mssql": 0,
"rdp": 0,
"ssh": 0,
"telnet": 0,
"vnc": 0
},
"sessions_total": 0,
"swap": 0,
"system_details": {
"cpu": {
"guest": 0.0,
"guest_nice": 0.0,
"idle": 94.6,
"iowait": 0.0,
"irq": 0.0,
"nice": 0.5,
"softirq": 0.0,
"steal": 1.0,
"system": 1.0,
"user": 3.0
},
"disk": {
"free": 26850131968,
"percent": 10.3,
"total": 31571550208,
"used": 3094085632
},
"memory": {
"active": 4459466752,
"available": 4492849152,
"buffers": 456245248,
"cached": 3229765632,
"free": 1336004608,
"inactive": 1984532480,
"percent": 46.3,
"shared": 249368576,
"total": 8364044288,
"used": 3342028800
},
"swap": {
"free": 0,
"percent": 0,
"sin": 0,
"sout": 0,
"total": 0,
"used": 0
}
}
},
"meta": {
"href": "/api/health-status",
"parent": "/api",
"remaining_seconds": 600
}
}
|
health_status |
|
null or object |
The health status of a node. When queried, it lists data related to the given node's health (in the case of HA, this means the current master node). |
|
memory |
floating point number |
Memory usage (percent) |
|
disk |
floating point number |
Hard disk usage (percent) |
|
swap |
floating point number |
Swap usage (percent) |
|
cpu |
floating point number |
Overall CPU usage (percent) |
|
load1 |
floating point number |
The average system load during the last one minute. |
|
load5 |
floating point number |
The average system load during the last five-minute period. |
|
load15 |
floating point number |
The average system load during the last fifteen-minute period. |
|
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. |
|
system_details |
JSON object |
Various details about the CPU, disk, memory and swap usage of the appliance. Note that the exact set of metrics is determined by the underlying kernel and system libraries, therefore it might change between different versions of Safeguard for Privileged Sessions without notice. |
The number of CPUs determine the load a system can handle without causing the processes having to wait. As a generic rule of thumb, if the load is less than the number of processor cores of the appliance, the overall system load can be considered normal, otherwise it might be an indication of performance issues.
Advanced authentication and authorization
Advanced authentication and authorization
Usermapping policy
For SSH, RDP, Telnet, and Citrix ICA connections, usermapping policies can be defined. A usermapping policy describes who can use a specific username to access the remote server: only members of the specified local or LDAP usergroups (for example, administrators) can use the specified username (for example, root) on the server.
URL
GET https://<IP-address-of-SPS>/api/configuration/policies/usermapping_policies
Cookies
| session_id |
Contains the authentication token of the user |
Required |
The value of the session ID cookie received from the REST server in the authentication response, for example, a1f71d030e657634730b9e887cb59a5e56162860. For details on authentication, see Authenticate to the SPS REST API.
Note that this session ID refers to the connection between the REST client and the SPS REST API. It is not related to the sessions that SPS records (and which also have a session ID, but in a different format). |
Sample request
The following command lists the existing usermapping policies.
curl --cookie cookies https://<IP-address-of-SPS>/api/configuration/policies/usermapping_policies
The following command retrieves the properties of a specific usermapping policy.
curl --cookie cookies https://<IP-address-of-SPS>/api/configuration/policies/usermapping_policies<object-id>
Response
The following is a sample response received when listing usermapping policies.
For details of the meta object, see Message format.
{
"meta": {
"first": "/api/configuration/policies/audit_policies",
"href": "/api/configuration/policies/usermapping_policies",
"last": "/api/configuration/policies/usermapping_policies",
"next": null,
"parent": "/api/configuration/policies",
"previous": "/api/configuration/policies/userlists",
"transaction": "/api/transaction"
},
"items": [
{
"key": "11581153055704544883f77",
"meta": {
"href": "/api/configuration/policies/usermapping_policies/11581153055704544883f77"
}
},
{
"key": "9328731525704545f5e3de",
"meta": {
"href": "/api/configuration/policies/usermapping_policies/9328731525704545f5e3de"
}
}
]
}
When retrieving the endpoint of a specific host key, the response is the following.
{
"body": {
"allow_other_remote_users_without_mapping": false,
"mappings": [
{
"allowed_groups": [],
"remote_user": "test"
},
{
"allowed_groups": [
"admins"
],
"remote_user": "root"
}
],
"name": "Test"
},
"key": "9328731525704545f5e3de",
"meta": {
"first": "/api/configuration/policies/usermapping_policies/277736452570454272e157",
"href": "/api/configuration/policies/usermapping_policies/9328731525704545f5e3de",
"last": "/api/configuration/policies/usermapping_policies/9328731525704545f5e3de",
"next": null,
"parent": "/api/configuration/policies/usermapping_policies",
"previous": "/api/configuration/policies/usermapping_policies/11581153055704544883f77",
"transaction": "/api/transaction"
}
}
| key |
|
|
string |
Top level element, contains the ID of the policy. |
| body |
|
|
Top level element (string) |
The elements of the usermapping policy. |
|
allow_other_remote_users_without_mapping |
|
boolean |
Default value: true.
To allow access the remote servers for users who are not explicitly listed in the Usermapping Policy, configure true. Note that these users must use the same username on the SPS gateway and the remote server. |
|
mappings |
|
Top level list |
Contains the list of user groups and the corresponding remote usernames the group members can use to log in. |
|
|
allowed_groups |
list |
The usergroups allowed to log in as the remote_user on the remote server.
Required element. Empty means all users. |
|
|
remote_user |
string |
The username on the remote server that the users configured in allowed_groups can use to log in.
Required element. Must have a value. |
Example mappings:
Anyone can log in to the remote server as the test user:
"mappings": [
{
"allowed_groups": [],
"remote_user": "test"
}
Only the members of the admin group can log in to the remote server as the root user:
"mappings": [
{
"allowed_groups": [
"admins"
],
"remote_user": "root"
}
Status and error codes
The following table lists the typical status and error codes for this request. For a complete list of error codes, see Application level error codes.
| 201 |
Created |
The new resource was successfully created. |
| 400 |
InvalidQuery |
The requested filter or its value is invalid. |
| 401 |
Unauthenticated |
The requested resource cannot be retrieved because the client is not authenticated and the resource requires authorization to access it. The details section contains the path that was attempted to be accessed, but could not be retrieved. |
| 403 |
Unauthorized |
The requested resource cannot be retrieved because the client is not authorized to access it. The details section contains the path that was attempted to be accessed, but could not be retrieved. |
| 404 |
NotFound |
The requested object does not exist. |
Add a usermapping policy
To add a usermapping policy, you have to:
-
Open a transaction.
For more information, see Open a transaction.
-
Create the JSON object for the new usermapping policy.
POST the JSON object to the https://<IP-address-of-SPS>/api/configuration/policies/usermapping endpoint. You can find a detailed description of the available parameters listed in Element .
If the POST request is successful, the response includes the key of the new usermapping policy. For example:
{
"key": "2e8692fa-7fda-4753-8363-37e8244f6b80",
"meta": {
"href": "/api/configuration/policies/usermapping_policies/2e8692fa-7fda-4753-8363-37e8244f6b80",
"parent": "/api/configuration/policies/usermapping_policies",
"transaction": "/api/transaction"
}
}
-
Commit your changes.
For more information, see Commit a transaction.
Modify a usermapping policy
To modify a usermapping policy, you have to:
-
Open a transaction.
For more information, see Open a transaction.
-
Modify the JSON object of the usermapping policy.
PUT the modified JSON object to the https://<IP-address-of-SPS>/api/configuration/policies/usermapping/<key-of-the-object> endpoint. You can find a detailed description of the available parameters listed in Element .
-
Commit your changes.
For more information, see Commit a transaction.
Plugins
Contains the endpoints for configuring plugins.
URL
GET https://<IP-address-of-SPS>/api/configuration/plugins
Cookies
| session_id |
Contains the authentication token of the user |
Required |
The value of the session ID cookie received from the REST server in the authentication response, for example, a1f71d030e657634730b9e887cb59a5e56162860. For details on authentication, see Authenticate to the SPS REST API.
Note that this session ID refers to the connection between the REST client and the SPS REST API. It is not related to the sessions that SPS records (and which also have a session ID, but in a different format). |
Sample request
The following command lists endpoints for configuring plugins.
curl --cookie cookies https://<IP-address-of-SPS>/api/configuration/plugins
Response
The following is a sample response received when listing endpoints for configuring plugins.
For details of the meta object, see Message format.
{
"items": [
{
"key": "aa",
"meta": {
"href": "/api/configuration/plugins/aa"
}
},
{
"key": "configuration_sync",
"meta": {
"href": "/api/configuration/plugins/configuration_sync"
}
},
{
"key": "credentialstore",
"meta": {
"href": "/api/configuration/plugins/credentialstore"
}
},
{
"key": "signingca",
"meta": {
"href": "/api/configuration/plugins/signingca"
}
}
],
"meta": {
"first": "/api/configuration/aaa",
"href": "/api/configuration/plugins",
"last": "/api/configuration/x509",
"next": "/api/configuration/policies",
"parent": "/api/configuration",
"previous": "/api/configuration/passwords",
"remaining_seconds": 600,
"transaction": "/api/transaction"
}
}
| aa |
Endpoint for configuring authentication and authorization plugins. |
| configuration_sync |
Endpoint for configuring plugins that synchronize the configuration of SPS clusters that receive their configuration from the Central Management node. |
| credentialstore |
Endpoint for configuring credential store plugins. |
| signingca |
Endpoint for configuring plugins to sign certificates. |
Status and error codes
The following table lists the typical status and error codes for this request. For a complete list of error codes, see Application level error codes.
| 401 |
Unauthenticated |
The requested resource cannot be retrieved because the client is not authenticated and the resource requires authorization to access it. The details section contains the path that was attempted to be accessed, but could not be retrieved. |
| 403 |
Unauthorized |
The requested resource cannot be retrieved because the client is not authorized to access it. The details section contains the path that was attempted to be accessed, but could not be retrieved. |
| 404 |
NotFound |
The requested object does not exist. |
