Chat now with support
Chat with Support

One Identity Safeguard for Privileged Sessions 7.0.3 LTS - REST API Reference Guide

Introduction Using the SPS REST API Basic settings User management and access control Managing SPS General connection settings HTTP connections Citrix ICA connections MSSQL connections RDP connections SSH connections Telnet connections VNC connections Search, download, and index sessions Reporting Health and maintenance Advanced authentication and authorization Completing the Welcome Wizard using REST Enable and configure analytics using REST

Configuring LDAP servers

Configure LDAP AD and LDAP POSIX servers for authentication, authorization, and accounting (AAA).

URL
POST https://<IP-address-of-SPS>/api/configuration/aaa/ldap_servers
Cookies
Cookie name Description Required Values
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 more information on authentication, see Authenticate to the SPS REST API.

NOTE: 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).
Operations

Operations with the /aaa/ldap_servers endpoint include:

Operation HTTP method URL

Notes
Creating a new LDAP server POST /api/configuration/aaa/ldap_servers

 

Retrieving a LDAP server

GET

 

Sample request

The following command creates a new LDAP server.

curl --cookie cookies https://<IP-address-of-SPS>/api/configuration/aaa/ldap_servers

The following is a sample request.

{
     "name": "ldap-server-name",
     "schema": {
       "selection": "posix",
       "username_attribute": "uid",
       "membership_check": {
         "enabled": true,
         "member_uid_attribute": "memberUid"
       },
       "memberof_check": {
         "enabled": true,
         "memberof_user_attribute": "memberOf",
         "memberof_group_objectclass": "groupOfNames"
       },
       "user_dn_in_groups": [
         {
           "object_class": "groupOfNames",
           "attribute": "member"
         },
         {
           "object_class": "groupOfUniqueNames",
           "attribute": "uniqueMember"
         }
       ]
     },
     "servers": [
       {
         "host": {
           "selection": "ip",
           "value": "10.110.0.1"
         },
         "port": 389
       }
     ],
     "user_base_dn": "ou=People,dc=example",
     "group_base_dn": "ou=Groups,dc=example",
     "bind_dn": null,
     "bind_password": null,
     "encryption": {
       "selection": "disabled"
     }
   }
Response

The following is a sample response received when you retrieve LDAP server information.

For more information on the meta object, see Message format.

{
     "items": [
       {
         "body": {
           "bind_dn": null,
           "bind_password": null,
           "encryption": {
             "selection": "disabled"
           },
           "group_base_dn": "ou=Groups,dc=example",
           "name": "ldap-server-name",
           "schema": {
             "memberof_check": {
               "enabled": true,
               "memberof_group_objectclass": "groupOfNames",
               "memberof_user_attribute": "memberOf"
             },
             "membership_check": {
               "enabled": true,
               "member_uid_attribute": "memberUid"
             },
             "selection": "posix",
             "user_dn_in_groups": [
               {
                 "attribute": "member",
                 "object_class": "groupOfNames"
               },
               {
                 "attribute": "uniqueMember",
                 "object_class": "groupOfUniqueNames"
               }
             ],
             "username_attribute": "uid"
           },
           "servers": [
             {
               "host": {
                 "selection": "ip",
                 "value": "10.110.0.1"
               },
               "port": 389
             }
           ],
           "user_base_dn": "ou=People,dc=example"
         },
         "key": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
         "meta": {
           "href": "/api/configuration/aaa/ldap_servers/XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"
         }
       }
     ]
   }

Elements of the response message body include:

Element

Type

 Description

Notes
bind_dn

string

The Distinguished Name that SPS should use to bind to the LDAP directory.

Must be used if the value of the selection element is set to ldap.

NOTE: SPS accepts both pre Windows 2000-style and Windows 2003-style account names, or User Principal Names (UPNs). For example, administrator@example.com is also accepted.

bind_password null | string

References the password SPS uses to authenticate on the server. You can configure passwords at the /api/configuration/passwords/ endpoint.

Must be used if the value of the selection element is set to ldap.

To modify or add a password, use the value of the returned key as the value of the password element, and remove any child elements (including the key).

NOTE: SPS accepts passwords that are not longer than 150 characters and supports the following characters:

  • Letters A-Z, a-z

  • Numbers 0-9

  • The space character

  • Special characters: !"#$%&'()*+,-./:;<>=?@[]\^-`{}_|

encryption union

Configuration settings for encrypting the communication between SPS and the LDAP server.

The displayed value type depends on the encryption.selection parameter.

encryption.selection enum

Defines the type of encryption SPS uses to communicate with the LDAP server. Possible values are:

  • disabled

    The communication is not encrypted.

  • ssl

    TLS/SSL encryption. To use a TLS-encrypted with certificate verification to connect to the LDAP server, use the full domain name (for example ldap.example.com) as the server address, otherwise the certificate verification might fail. The name of the LDAP server must appear in the Common Name of the certificate.

    NOTE: TLS-encrypted connection to Microsoft Active Directory is supported only on Windows 2003 Server and newer platforms. Windows 2000 Server is not supported.

  • starttls

    Opportunistic TLS.

  • Example if the value is disabled

    {
  "selection": "disabled"
}

  • Example if the value is ssl or starttls:

    {
  "selection": "ssl | starttls",
  "trust_store": null|<trust-store-ref>,
  "client_authentication": null|<x509-ref>
}

group_base_dn

string

Name of the DN to be used as the base of queries regarding groups.

NOTE: You must fill in this field. It is OK to use the same value for user_base_dn and group_base_dn.

However, note that specifying a sufficiently narrow base for the LDAP subtrees where users and groups are stored can speed up LDAP operations.

Example:

"ou=users,ou=example"

name

string

Top level element, the name of the object. This name is also displayed on the SPS web interface. It cannot contain whitespace.

 

schema

union

AD and POSIX specific LDAP configuration.

  • Example with LDAP AD server, where the schema selection is ad:

    {
  "selection": "ad",
  "membership_check": ...,
  "memberof_check": ...,
  "user_dn_in_groups": …
}

  • Example with LDAP POSIX server, where the schema selection is posix:

    {
  "selection": "posix",
  "membership_check": ...,
  "memberof_check": ...,
  "user_dn_in_groups": ...,
  "username_attribute": …
}

schema.memberof_check

object

The Enable checking for group DNs in user objects setting allows checking a configurable attribute in the user object. This attribute contains a list of group DNs the user is additionally a member of. This user attribute is usually memberOf.

  • Example with LDAP AD server, if memberof_check and memberof_user_attribute are enabled:

    "schema": {
               "memberof_check": {
                 "enabled": true,
                 "memberof_user_attribute": "memberOf"
               }

  • Example with LDAP POSIX server, if memberof_check is enabled:

    "schema": {
               "memberof_check": {
                 "enabled": true,
                 "memberof_group_objectclass": "groupOfNames",
                 "memberof_user_attribute": "memberOf"
               }

  • To disable memberof_check for both LDAP AD and LDAP POSIX servers, set the enabled parameter to false.

    "schema": {
               "memberof_check": {
                 "enabled": false
               }

schema.memberof_check.enabled

boolean

To enable memberof_check, set it to true.

 

schema.memberof_check.memberof_group_objectclass

string

The attribute holding the members of the LDAP group.

This field is case-sensitive.

Default value: groupOfNames

schema.memberof_check.memberof_user_attribute

string

Must be used if the memberof_check is set it to true. The name of the user attribute (for example, memberOf) that contains the group DNs.

This attribute is the same for both LDAP AD and LDAP POSIX schema.

schema.membership_check

object

  • POSIX: POSIX primary and supplementary group membership checking.

  • AD: Active Directory specific non-primary group membership checking.

  • Example with LDAP AD server, if membership_check and nested_groups are enabled:

    "membership_check": {
                "enabled": true,
                "nested_groups": true | false"
              }

  • Example with LDAP POSIX server, if membership_check and member_uid_attribute are enabled:

    "membership_check": {
                "enabled": true,
                "member_uid_attribute": null | "memberUid"
              }

  • To disable membership_check for both LDAP AD and LDAP POSIX servers, set the enabled parameter to false.

    "membership_check": {
                "enabled": false
              }

schema.membership_check.enabled

boolean

POSIX: Enables POSIX primary and supplementary group membership checking.

AD: Enables Active Directory specific non-primary group membership checking.

 

schema.membership_check.member_uid_attribute

string

Must be used if the value of the selection element is set to posix.

The POSIX group membership attribute name is the name of the attribute in a posixGroup group object, which lists the plain usernames that are members of the group. These groups are usually referred to as supplementary groups of the referred user. Can be null.

Default value: memberUid

schema.selection

string

Configures which LDAP schema to use: AD or POSIX. Possible values are:

  • ad: Microsoft Active Directory server. For details and examples, see Configuring LDAP servers.

  • posix: The server uses the POSIX LDAP scheme.

    Must be used with the member_uid_attribute and username_attribute elements. For details and examples, see Configuring LDAP servers.

Default value: ad, posix

schema.user_dn_in_groups

array

Add object_class / attribute pairs. SPS will search for the user DN in the group's attribute defined here. If it finds the user DN there, SPS considers the user the member of that group.

Example:

"user_dn_in_groups": [
                  {
                    "attribute": "member",
                    "object_class": "groupOfNames"
                  },
                  {
                    "attribute": "uniqueMember",
                    "object_class": "groupOfUniqueNames"
                  }
                ]

The array can return empty:

"user_dn_in_groups": []

user_dn_in_groups can serve as additional validation. At least one out of membership_check, memberof_check or user_dn_in_groups must be filled for validation.

schema.user_dn_in_groups.attribute

string

Name of the group attribute which contains the user DN.

Default value: member

schema.user_dn_in_groups.object_class

string

Consider groups of this objectClass.

Possible values: groupOfNames, groupOfUniqueNames

schema.username_attribute

string

The login attribute that uniquely identifies a single user record.

Default value: uid

servers

array

Contains the addresses and ports of the LDAP servers.

The displayed value type depends on the servers.host.selection parameter.

Possible values are: ip, fqdn

  • Example if the host selection is ip:

    "servers": [
                {
                  "host":{
                    "selection": "ip",
                    "value": "1.2.3.4"
                  },
                  "port": 123
                }
              ],

  • Example, if the host selection is fqdn:

    "servers": [
                {
                  "host": {
                    "selection": "fqdn",
                    "value": "my.example"
                  },
                  "port": 123
                }
              ],

servers.host

object

Contains the address of the LDAP server.

 

servers.host.selection

string

Defines the address type (IP or domain name).

Possible values are:

  • fqdn

    The LDAP server address is provided as a fully qualified domain name.

  • ip

    The LDAP server address is provided as an IP address.

servers.host.value

string

The address of the LDAP server.

 

servers.port

int

The port of the LDAP server.

 

user_base_dn

string

Name of the DN to be used as the base of queries regarding users.

Must be used if the value of the selection element is set to ldap.

NOTE: You must fill in this field. It is OK to use the same value for user_base_dn and group_base_dn.

However, note that specifying a sufficiently narrow base for the LDAP subtrees where users and groups are stored can speed up LDAP operations.

For example:

"ou=groups,ou=example"
Configure LDAP servers

To configure an LDAP server, you have to:

  1. Open a transaction.

    For more information, see Open a transaction.

  2. Create the JSON object for the new LDAP server configuration.

    POST the JSON object to the https://<IP-address-of-SPS>/api/configuration/aaa/ldap_servers endpoint. You can find a detailed description of the available parameters listed in Element .

  3. Commit your changes.

    For more information, see Commit a transaction.

HTTP response codes

For more information and a complete list of standard HTTP response codes, see Application level error codes.

Configuring SPS login methods

Use the /aaa/login_methods endpoint to configure multiple login methods for SPS. Possible login methods are the following:

  • Local login

  • LDAP login (AD or POSIX)

  • X509 login

  • RADIUS login

URL
POST https://<IP-address-of-SPS>/api/configuration/aaa/login_methods
Cookies
Cookie name Description Required Values
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 more information on authentication, see Authenticate to the SPS REST API.

NOTE: 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).
Operations

Operations with the /aaa/login_methods endpoint include:

Operation HTTP method URL

Notes

Configuring the Local login method

 POST

 

 

 

 /api/configuration/aaa/login_methods

 

NOTE: Changing your password is possible only with Local login.

Configuring the X509 login method

Before you can configure the X509 login method, you must upload your X509 certificate to a trust store at the /api/configuration/trust_stores endpoint.

Configuring the password-based LDAP login method (AD or POSIX)

Before you can configure the LDAP login method, you must create a new LDAP server at the /api/configuration/aaa/ldap_servers endpoint.

Configuring the RADIUS login method

 

Reordering login methods

PUT

/api/configuration/aaa/login_methods/@order

By default, the Local login method button appears as the first login method on the SPS web interface. To reorder the login method buttons, use the /@order endpoint.

Sample request

The following command creates a new login method.

curl --cookie cookies https://<IP-address-of-SPS>/api/configuration/aaa/login_methods

The following parameters are applicable to all login methods - Local, LDAP, X509, and RADIUS.

Element

Type

 Description

Notes
type

enum

The login method type used for authentication.

Possible values are:

  • local

    Use a local user database for authentication.

  • x509

    Use a X509 certificate for authentication.

  • ldap

    Use an LDAP server (AD or POSIX) for authentication.

  • radius

    Use a RADIUS server for authentication.

name

string

A unique identifier of the login method.
title

string

 The title that appears above the login method button on the SPS web interface. This can be customized. In the case of X509 login method, there is only one button.
active

boolean

Indicates whether the login method is enabled or not.

  
Example: Sample request for configuring Local login
{
     "type": "local",
     "name": "inactive-local",
     "title": "Local login",
     "active": false,
     "cracklib_enabled": true,
     "expiration_days": 30,
     "remember_previous_passwords": 10,
     "minimum_password_strength": "good",
     "minimum_password_length": 1
   }

Elements of the request message body include:

Element

Type

 Description

Notes
cracklib_enabled

boolean

Password setting. Must be used if the value of the selection element is set to local.

Set to true to test the strength of user passwords with simple dictionary attacks before they are committed.

Set to false if a RADIUS server or X.509 certificate is used for authentication.

NOTE: The strength of a password is determined by its length and complexity: the variety of numbers, letters, capital letters, and special characters used.

To run simple dictionary-based attacks to find weak passwords, enable Cracklib (eg. dictionary) protection.

expiration_days

integer

Password setting. Configures the number of days the user passwords are considered valid. Expired passwords must be changed upon login.

Set to 0 if a RADIUS server or X.509 certificate is used for authentication.

The 0 value means the passwords do not expire. The highest value you can configure is 365.

Must be used if the value of the selection element is set to local.

remember_previous_passwords

integer

Password setting. Configures the number of previous passwords to retain to prevent password reuse.

Set to 0 if a RADIUS server or X.509 certificate is used for authentication.

The 0 value means passwords can be reused.

Must be used if the value of the selection element is set to local.

minimum_password_strength

string

Password setting. Configures the required password strength for new passwords.

Set to disabled if a RADIUS server or X.509 certificate is used for authentication.

Possible values are:

  • disabled

    Any password is accepted.

  • good

    Weak passwords are not accepted.

  • strong

    Only strong passwords are accepted.

Must be used if the value of the selection element is set to local.

minimum_password_length

number

The minimum number of characters the password must consist of.

 

Example: Sample request for configuring LDAP login
{
     "type": "ldap",
     "name": "ldap",
     "title": "LDAP login",
     "active": true,
     "ldap_server": "5ed1b422-395a-4d5e-abf0-b43cd6c752f8"
   }

Elements of the request message body include:

Element

Type

 Description

Notes
ldap_server

string

The identifier of the previously created LDAP server.

  
Example: Sample request for configuring X509 login
{
     "type": "x509",
     "name": "x509",
     "title": "X509 login",
     "active": true,
     "trust_store": "5ed1b422-395a-4d5e-abf0-b43cd6c752f8",
     "username_attribute": "commonName",
     "groups": {
       "type": "local"
     }
   }

Elements of the request message body include:

Element

Type

 Description

Notes
trust_store

string

The identifier of the X509 certificate that was previously uploaded into Trust stores.

Trust stores serve as local certificate storages where users can store the certificate chains of trusted Certificate Authorities (CAs).

username_attribute

enum

The login attribute that uniquely identifies a single user record. You can choose which type of username you want to use.

Possible values are:

  • commonName

  • emailAddress

  • userId

  • userPrincipalName

groups

object

 The location of your group from which you will authorize access.  
groups.type

enum

The type of the group.

Possibe values are:

  • local
  • ldap

If the group type is ldap, the identifier of the previously created LDAP server (the value of the ldap_server field) will appear.

Example: Configuring X509 login with LDAP groups

To configure a X509 login with LDAP groups

  2. Open a transaction.

    For more information, see Open a transaction.

  3. Create a new LDAP server at the /api/configuration/aaa/ldap_servers endpoint.

    {
     "name": "ldap_server",
     "schema": {
         "selection": "posix",
         "username_attribute": "uid",
         "membership_check": {
             "enabled": true,
             "member_uid_attribute": "memberUid"
         },
         "memberof_check": {
             "enabled": true,
             "memberof_user_attribute": "memberOf",
             "memberof_group_objectclass": "groupOfNames"
         },
         "user_dn_in_groups": [
             {
                 "object_class": "groupOfNames",
                 "attribute": "member"
             },
             {
                 "object_class": "groupOfUniqueNames",
                 "attribute": "uniqueMember"
             }
         ]
     },
     "servers": [
         {
             "host": {
                 "selection": "ip",
                 "value": "1.2.3.4"
             },
             "port": 389
         }
     ],
     "user_base_dn": "ou=People,dc=example",
     "group_base_dn": "ou=Groups,dc=example",
     "bind_dn": null,
     "bind_password": null,
     "encryption": {
         "selection": "disabled"
     }
}

  4. Upload a X509 certificate at the /api/configuration/trust_stores endpoint.

    {
     "name": "X509_Trust_Store",
     "authorities": [
         "-----BEGIN CERTIFICATE-----\nMIIDZzCCAk+gAwIBAgIUMlI5+EgTDAh2zqRDGYrzFRyozI8wDQYJKoZIhvcNAQEL\nBQAwQzELMAkGA1UEBhMCSFUxETAPBgNVBAgMCEJ1ZGFwZXN0MSEwHwYDVQQKDBhJ\nbnRlcm5ldCBXaWRnaXRzIFB0eSBMdGQwHhcNMTQwODEyMTIzNjQ4WhcNMzQwNjE4\nMTIzNjQ4WjBDMQswCQYDVQQGEwJIVTERMA8GA1UECAwIQnVkYXBlc3QxITAfBgNV\nBAoMGEludGVybmV0IFdpZGdpdHMgUHR5IEx0ZDCCASIwDQYJKoZIhvcNAQEBBQAD\nggEPADCCAQoCggEBALffJBDD6A/ZGBTgFbyLXHulU+hGnMW3DoPo2q4HY1/FfbkS\nrzmK+Fiz+3EwJCWi+EwK9mqve/nh6YRRw/VaAVQ7CkA7f7to+I7gP647Bq1wk0lh\nBVEJNlN0jfYYSumGxzPotw/fon1MkXuMbLc0Pr/vFX3NQC7/STAV5dZFcdboXDA7\nZZ3rzBIr93ThObsGj01MRO6wrS3rfE7Px9D7C2u9YSkP3OQ1Sfm/jqyLNaT6xt4i\nhrLnfYEc8mClnrlvILi+q/D6mIUSjb4IGvergAyl4jgPjO02UcvBzOIA9tDlBJBi\nQxZx+T620ubmEwOl9Q0G8RAWKz7szrBcXEjXhYUCAwEAAaNTMFEwHQYDVR0OBBYE\nFCDfEeq5Hsm8jMrG110iNpt5cikTMB8GA1UdIwQYMBaAFCDfEeq5Hsm8jMrG110i\nNpt5cikTMA8GA1UdEwEB/wQFMAMBAf8wDQYJKoZIhvcNAQELBQADggEBAK3iizM4\nCx69YD+4CWOUswULrCJA38C+nDYONLbNkact8JKXqCn/MaZTII+dZoV9RjjX4AzA\nPTQkZT+RoVeCZyt+qWHMdjq6koabXwQmXNozUtaxEZTrnoUDEWtNIbjV/gNtRcSG\nsU7i9L2YnwDzTw0cR/pu1Hykq8fwqNqjQGYnmXtJspMkKAtVe1CrtnPLiC6JBr0g\n5GZF58sHx5+gO0RkqdzJgRAGnImdfAahqfHmKRFmxoxWLyylRyqDgQ+KqcaDvZI+\ni36M+NQHVrDX4jo4CFoXhFlSOepvtDOpmzoWhugwDNMPuU1IEY7//CJBXQnjp+uf\nLO6PsNmMKDGi9Dk=\n-----END CERTIFICATE-----\n"
     ],
     "crl_urls": [
         "http://crl.it/sec"
     ],
     "revocation_check": "full"
}

  5. Create a new LDAP login method at the /api/configuration/aaa/login_methods endpoint.

    {
     "type": "x509",
     "name": "x509",
     "title": "X509 login",
     "active": true,
     "trust_store": "5ed1b422-395a-4d5e-abf0-b43cd6c752f8",
     "username_attribute": "commonName",
     "groups": {
        "type": "ldap",
        "ldap_server": "5ed1b422-395a-4d5e-abf0-b43cd6c752f8"
     }
}
  7. Commit your changes.

    For more information, see Commit a transaction.

Example: Configuring RADIUS login with local groups

To configure a RADIUS login with local groups

  2. Open a transaction.

    For more information, see Open a transaction.

  3. Create a new secret for your RADIUS server at the /api/configuration/passwords/ endpoint. For example, any.secret.

  4. Create a new RADIUS login method at the /api/configuration/aaa/login_methods endpoint.

    {
     "type": "radius",
     "name": "radius",
     "title": "Radius login",
     "active": true,
     "servers": [
         {
           "address": {
             "selection": "ip",
             "value": "4.5.6.7"
           },
           "port": 1812,
           "shared_secret": "<'key' from the response of the penultimate creation>"
         },
         {
           "address": {
             "selection": "fqdn",
             "value": "radius.example"
           },
           "port": 18120,
           "shared_secret": "<'key' from the response of the last creation>"
         }
     ],
     "authentication_protocol": "pap",
     "groups": {
         "type": "local"
     }
}
  6. Commit your changes.

    For more information, see Commit a transaction.

Example: Configuring RADIUS login with LDAP groups (AD or POSIX)

To configure a RADIUS login with LDAP groups

  2. Open a transaction.

    For more information, see Open a transaction.

  3. Create a new LDAP server at the /api/configuration/aaa/ldap_servers endpoint.

  4. Create a new secret for your RADIUS server at the /api/configuration/passwords/ endpoint. For example, any.secret.

  5. Create a new LDAP server login method at the /api/configuration/aaa/login_methods endpoint.

    {
     "type": "radius",
     "name": "radius",
     "title": "Radius login",
     "active": true,
     "servers": [
         {
             "address": {
               "selection": "fqdn",
               "value": "radius.balabit"
             },
             "port": 18120,
             "shared_secret": "<'key' from the response of the last creation>"
         }
     ],
     "authentication_protocol": "pap",
     "groups": {
         "type": "ldap",
         "ldap_server": "<'key' from the response of the penultimate creation>"
     }
}
  7. Commit your changes.

    For more information, see Commit a transaction.

Response

For more information on the meta object, see Message format.

HTTP response codes

For more information and a complete list of standard HTTP response codes, see Application level error codes.

Managing SPS

Topics:

Troubleshooting options

Configures debug logging and the retention time of core dump files.

  • Debug logging increases the log level of the non-network-related events, adding the commands executed by the SPS web interface to the log.

  • SPS automatically generates core dump files if an important software component of the system crashes. These core dump files can be of great help to the One Identity Support Team to identify problems. To download the generated core dump files, navigate to Basic Settings > Troubleshooting > Core files on the web interface of SPS.

URL
GET https://<IP-address-of-SPS>/api/configuration/troubleshooting
Cookies
Cookie name Description Required Values
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 more information on authentication, see Authenticate to the SPS REST API.

NOTE: 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 queries the troubleshooting settings.

curl --cookie cookies https://<IP-address-of-SPS>/api/configuration/troubleshooting
Response

The following is a sample response received.

For more information on the meta object, see Message format.

{
  "body": {
    "core_files": {
      "retention_days": 14
    },
    "debug_logging": {
      "enabled": true
    }
  },
  "key": "troubleshooting",
  "meta": {
    "first": "/api/configuration/aaa",
    "href": "/api/configuration/troubleshooting",
    "last": "/api/configuration/x509",
    "next": "/api/configuration/vnc",
    "parent": "/api/configuration",
    "previous": "/api/configuration/telnet",
    "transaction": "/api/transaction"
  }
}
Element Type Description
key string Top level element, contains the ID of the endpoint.
body Top level element (string) Contains the troubleshooting settings.
core_files Top level item Contains the settings for core dump file retention.
retention_days int Retention time for core files, in days.
debug_logging Top level item Settings for debug logging.
enabled boolean Set to true to increase the log level of the non-network-related events, adding the commands executed by the SPS web interface to the log.
Modify troubleshooting settings

To modify troubleshooting settings, you have to:

  1. Open a transaction.

    For more information, see Open a transaction.

  2. Modify the JSON object of the troubleshooting options.

    PUT the modified JSON object to the https://<IP-address-of-SPS>/api/configuration/troubleshooting endpoint. You can find a detailed description of the available parameters listed in Element .

  3. Commit your changes.

    For more information, see Commit a transaction.

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.

Code Description Notes
201 Created The new resource was successfully created.
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.
Related Documents

The document was helpful.

Select Rating

I easily found the information I needed.

Select Rating