External SNMP agents can query the basic status information of SPS. On this endpoint you can configure on which interfaces can the users access SPS, and optionally restrict the access to these interfaces, and configure authentication and encryption settings.
GET https://<IP-address-of-SPS>/api/configuration/local_services/snmp_agent
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 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). |
The following command lists the configuration options.
curl --cookie cookies https://<IP-address-of-SPS>/api/configuration/local_services/snmp_agent
The following is a sample response received when listing the configuration options.
For details of the meta object, see Message format.
{ "body": { "access_restriction": { "enabled": false }, "enabled": true, "listen": [ { "address": { "key": "nic1.interfaces.ff7574025754b3df1647001.addresses.1", "meta": { "href": "/api/configuration/network/nics/nic1#interfaces/ff7574025754b3df1647001/addresses/1" } }, "port": 161 } ], "system_contact": "mycontact", "system_description": "mydescription", "system_location": "mylocation", "version_2c": { "community": "mycommunity", "enabled": true }, "version_3": { "enabled": true, "users": [ { "auth_method": "sha", "auth_password": { "key": "5476940c-ba38-4002-96d4-cb09d6921c68", "meta": { "href": "/api/configuration/passwords/5476940c-ba38-4002-96d4-cb09d6921c68" } }, "encryption_method": "aes", "encryption_password": { "key": "99782a91-63de-4a5c-82ff-b82273894dc7", "meta": { "href": "/api/configuration/passwords/99782a91-63de-4a5c-82ff-b82273894dc7" } }, "username": "myusername" } ] } }, "key": "snmp_agent", "meta": { "first": "/api/configuration/local_services/admin_web", "href": "/api/configuration/local_services/snmp_agent", "last": "/api/configuration/local_services/user_web", "next": "/api/configuration/local_services/ssh", "parent": "/api/configuration/local_services", "previous": "/api/configuration/local_services/postgresql", "transaction": "/api/transaction" } }
Element | Type | Description | ||
---|---|---|---|---|
key | string | Top level element, contains the ID of the endpoint. | ||
body | Top level element (string) | Contains the configuration options of the SNMP agent. | ||
access_restriction |
JSON object |
Enables and configures limitations on the clients that can access the web interface, based on the IP address of the clients. | ||
allowed_from |
list |
The list of IP networks from where the administrators are permitted to access this management interface. To specify the IP addresses or networks, use the IPv4-Address/prefix format, for example, 10.40.0.0/16. | ||
enabled |
boolean |
Set it to true to restrict access to the specified client addresses. | ||
enabled | boolean | Enables the SNMP server. If this option is set to False, SPS ignores every other option of this endpoint. | ||
listen | list | Selects the network interface, IP address, and port where the clients can access the web interface. | ||
address | JSON object |
A reference to a configured network interface and IP address where this local service accepts connections. For example, if querying the interface /api/configuration/network/nics/nic1#interfaces/ff7574025754b3df1647001/addresses/ returns the following response: { "body": { "interfaces": { "@order": [ "ff7574025754b3df1647001" ], "ff7574025754b3df1647001": { "addresses": { "1": "10.40.255.171/24", "@order": [ "1" ] }, "name": "default", "vlantag": 0 } }, "name": "eth0", "speed": "auto" }, "key": "nic1", "meta": { "first": "/api/configuration/network/nics/nic1", "href": "/api/configuration/network/nics/nic1", "last": "/api/configuration/network/nics/nic3", "next": "/api/configuration/network/nics/nic2", "parent": "/api/configuration/network/nics", "previous": null, "transaction": "/api/transaction" } } Then the listening address of the local service is the following. nic1.interfaces.ff7574025754b3df1647001.addresses.1 This is the format you have to use when configuring the address of the local service using REST: "address": "nic1.interfaces.ff7574025754b3df1647001.addresses.1" When querying a local services endpoint, the response will contain a reference to the IP address of the interface in the following format: "address": { "key": "nic1.interfaces.ff7574025754b3df1647001.addresses.1", "meta": { "href": "/api/configuration/network/nics/nic1#interfaces/ff7574025754b3df1647001/addresses/1" } }, | ||
port | integer |
The port number where this local service accepts connections. | ||
system_contact | string | Optional. For example, it can contain the contact information of the SPS administrator. | ||
system_description | string | Optional. For example, it can contain information of the SPS host. | ||
system_description | string | Optional. For example, it can contain the location of the SPS appliance. | ||
version_2c | JSON object |
Enables and configures SNMP queries using the SNMP v2c protocol. You can have both the SNMP v2c and v3 protocols enabled at the same time. For example: "version_2c": { "community": "mycommunity", "enabled": true }, | ||
community | string | Optional. Specifies the community to use. | ||
enabled | boolean | Optional. Enables SNMP queries using the SNMP v2c protocol. | ||
version_3 | JSON object |
Enables and configures SNMP queries using the SNMP v3 protocol. You can have both the SNMP v2c and v3 protocols enabled at the same time. You must configure an authentication method and a password, encryption is optional. For example: "version_3": { "enabled": true, "users": [ { "auth_method": "sha", "auth_password": { "key": "5476940c-ba38-4002-96d4-cb09d6921c68", "meta": { "href": "/api/configuration/passwords/5476940c-ba38-4002-96d4-cb09d6921c68" } }, "encryption_method": "aes", "encryption_password": { "key": "99782a91-63de-4a5c-82ff-b82273894dc7", "meta": { "href": "/api/configuration/passwords/99782a91-63de-4a5c-82ff-b82273894dc7" } }, "username": "myusername" } ] } |
Elements of version_3 | Type | Description | |
---|---|---|---|
enabled | boolean | Optional. Enables SNMP queries using the SNMP v2c protocol. | |
users | JSON object | Contains the configuration parameters for the SNMP v3 protocol. | |
auth_method | string |
Required parameter when using SNMP version 3. Configures encrypted communication with the SNMP server. Possible values are:
| |
auth_password | string |
Required parameter when using SNMP version 3. References the password used for authenticating to the SNMP server. You can create passwords at the /api/configuration/passwords/ endpoint. To modify or add a password, use the value of the returned key as the value of the x509_identity element, and remove any child elements (including the key). The referenced password must be at least 8 characters long, and can contain letters (a-z, A-Z), numbers (0-9) the special characters (!"#$%&'()*+,;<=&@[\]^`{|}_./:?-) and the space character. | |
encryption_method | string |
Configures encrypted communication with the SNMP server. Possible values are:
| |
encryption_password | string |
Set to null if the value of the encryption_method is set to none. References the password used for encrypting the communication with the SNMP server. You can create passwords at the /api/configuration/passwords/ endpoint. To modify or add a password, use the value of the returned key as the value of the x509_identity element, and remove any child elements (including the key). The referenced password must be at least 8 characters long, and can contain letters (a-z, A-Z), numbers (0-9) the special characters (!"#$%&'()*+,;<=&@[\]^`{|}_./:?-) and the space character. | |
username | string |
The username for sending SNMP traps. |
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 |
---|---|---|
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. |
401 | AuthenticationFailure | Authenticating the user with the given credentials has failed. |
404 | NotFound | The requested object does not exist. |
Contains the endpoints for configuring alerting on SPS.
GET https://<IP-address-of-SPS>/api/configuration/alerting
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 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). |
The following command lists alerting configuration endpoints.
curl --cookie cookies https://<IP-address-of-SPS>/api/configuration/alerting
The following is a sample response received when listing alerting configuration endpoints.
For details of the meta object, see Message format.
{ "items": [ { "key": "system_alerts", "meta": { "href": "/api/configuration/alerting/system_alerts" } }, { "key": "traffic_alerts", "meta": { "href": "/api/configuration/alerting/traffic_alerts" } } ], "meta": { "first": "/api/configuration/aaa", "href": "/api/configuration/alerting", "last": "/api/configuration/x509", "next": "/api/configuration/datetime", "parent": "/api/configuration", "previous": "/api/configuration/aaa", "transaction": "/api/transaction" } }
Element | Description |
---|---|
system_alerts | Configuration options for system-related alerts. |
traffic_alerts | Configuration options for traffic-related alerts. |
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 |
---|---|---|
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. |
401 | AuthenticationFailure | Authenticating the user with the given credentials has failed. |
404 | NotFound | The requested object does not exist. |
Configuration options for sending system-related alerts.
E-mail alerts, when enabled, are sent to the e-mail address configured in the alerting_address element of the /api/configuration/management/email endoint.
SNMP alerts, when enabled, are sent to the SNMP server configured at the /api/configuration/management/snmp/trap endpoint.
GET https://<IP-address-of-SPS>/api/configuration/alerting/system_alerts
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 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). |
The following command lists configuration options for system-related alerts.
curl --cookie cookies https://<IP-address-of-SPS>/api/configuration/alerting/system_alerts
The following is a sample response received when listing configuration options for system-related alerts.
For details of the meta object, see Message format.
{ "body": { "xcbAlert": { "email": false, "snmp": false }, "xcbArchiveFailed": { "email": false, "snmp": false }, "xcbBackupFailed": { "email": false, "snmp": false }, "xcbBruteForceAttempt": { "email": false, "snmp": false }, "xcbConfigChange": { "email": false, "snmp": false }, "xcbDBError": { "email": false, "snmp": false }, "xcbDiskFull": { "email": false, "snmp": false }, "xcbError": { "email": false, "snmp": false }, "xcbFirmwareTainted": { "email": false, "snmp": false }, "xcbHWError": { "email": false, "snmp": false }, "xcbHaNodeChanged": { "email": false, "snmp": false }, "xcbLicenseAlmostExpired": { "email": false, "snmp": false }, "xcbLimitReached": { "email": false, "snmp": false }, "xcbLoadAvgHigh": { "email": false, "snmp": false }, "xcbLogin": { "email": false, "snmp": false }, "xcbLoginFailure": { "email": false, "snmp": false }, "xcbLogout": { "email": false, "snmp": false }, "xcbRaidStatus": { "email": false, "snmp": false }, "xcbSwapFull": { "email": false, "snmp": false }, "xcbTimeSyncLost": { "email": false, "snmp": false }, "xcbTimestampError": { "email": false, "snmp": false } }, "key": "system_alerts", "meta": { "first": "/api/configuration/alerting/system_alerts", "href": "/api/configuration/alerting/system_alerts", "last": "/api/configuration/alerting/traffic_alerts", "next": "/api/configuration/alerting/traffic_alerts", "parent": "/api/configuration/alerting", "previous": null, "transaction": "/api/transaction" } }
To enable or disable an alert, you have to:
For details, see Open a transaction.
PUT the modified JSON object to the https://<IP-address-of-SPS>/api/configuration/alerting/system_alerts endpoint. You can find a detailed description of the available parameters listed in Element .
For details, see Commit a transaction.
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. |
401 | AuthenticationFailure | Authenticating the user with the given credentials has failed. |
404 | NotFound | The requested object does not exist. |
Configuration options for sending traffic-related alerts.
E-mail alerts, when enabled, are sent to the e-mail address configured in the alerting_address element of the /api/configuration/management/email endoint.
SNMP alerts, when enabled, are sent to the SNMP server configured at the /api/configuration/management/snmp/trap endpoint.
GET https://<IP-address-of-SPS>/api/configuration/alerting/traffic_alerts
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 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). |
The following command lists the configuration options for traffic-related alerts..
curl --cookie cookies https://<IP-address-of-SPS>/api/configuration/alerting/traffic_alerts
The following is a sample response received when listing the configuration options for traffic-related alerts.
For details of the meta object, see Message format.
{ "body": { "scbAuthFailure": { "email": false, "snmp": false }, "scbAuthSuccess": { "email": false, "snmp": false }, "scbChannelDenied": { "email": false, "snmp": false }, "scbConnectionDenied": { "email": false, "snmp": false }, "scbConnectionFailed": { "email": false, "snmp": false }, "scbConnectionTimedout": { "email": false, "snmp": false }, "scbCredStoreClosed": { "email": false, "snmp": false }, "scbCredStoreDecryptError": { "email": false, "snmp": false }, "scbCredStoreUnlockFailure": { "email": false, "snmp": false }, "scbGWAuthFailure": { "email": false, "snmp": false }, "scbGWAuthSuccess": { "email": false, "snmp": false }, "scbProtocolViolation": { "email": false, "snmp": false }, "scbRealTimeAlert": { "email": false, "snmp": false }, "scbSshHostKeyLearned": { "email": false, "snmp": false }, "scbSshHostKeyMismatch": { "email": false, "snmp": false }, "scbUserMappingFailure": { "email": false, "snmp": false } }, "key": "traffic_alerts", "meta": { "first": "/api/configuration/alerting/system_alerts", "href": "/api/configuration/alerting/traffic_alerts", "last": "/api/configuration/alerting/traffic_alerts", "next": null, "parent": "/api/configuration/alerting", "previous": "/api/configuration/alerting/system_alerts", "transaction": "/api/transaction" } }
To enable or disable an alert, you have to:
For details, see Open a transaction.
PUT the modified JSON object to the https://<IP-address-of-SPS>/api/configuration/alerting/traffic_alerts endpoint. You can find a detailed description of the available parameters listed in Element .
For details, see Commit a transaction.
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. |
401 | AuthenticationFailure | Authenticating the user with the given credentials has failed. |
404 | NotFound | The requested object does not exist. |
© 2024 One Identity LLC. ALL RIGHTS RESERVED. Terms of Use Privacy Cookie Preference Center