...
You can use a session management template to specify settings that will be applied to an endpoint. You can define settings such as the timeout value after which the REST API outbound requests are aborted. This template can also contain additional child templates that can be referenced by the configuration. However, you cannot reference other templates in the system from the session management template.
Once you upload a session management template to the Grid, the configuration in the template automatically applies to the specified endpoint, if the connection to the endpoint has been established and if the template is assigned to the endpoint.
Table 45.2 lists the supported variables you can use in a session management template.
...
Variable | Type | Mandatory | Description |
|---|---|---|---|
version | Must be 3.0 | Yes | The version number of the template. Note that 3.0 is the latest version. The appliance still fully supports the previous schema version. |
type | Must be REST_ENDPOINT | Yes | The template type. |
name | String | Yes | The template name. |
vendor_identifier | String | Yes | The vendor identifier for an endpoint. |
comment | String | No | Additional information. |
path | String | No | Path string to append to what the user enters in the GUI. |
override_path | Boolean | No | If present, the path above replaces the path the user enters in the GUI. |
timeout | Integer | No | The timeout value in seconds. The minimum is 1 and the maximum is 3600. The default is 30. |
keepalive | Boolean | No | The value can be True or False. The default is False. |
| keepalive_timeout | Integer | No | The keepalive timeout value in seconds. The connection is closed after this timeout. The minimum is 1 and the maximum is 300. The default is 5. |
dxl_keepalive_timeout | Integer | No | The keepalive timeout value in seconds with a connected DXL broker. This controls the rate at which the client will send ping |
dxl_topic | String | No | The DXL topic that is used to send data by DXL. Note: This variable is applicable only for the DXL templates |
retry | Integer | No | The number of attempts to try to connect to the endpoint before considering the connection a failure (this covers only timeout/network errors). The default value is 2. |
retry_template | Integer | No | The number of attempts the appliance retries the full template if it returns a failure (this covers a template returning anything but 200). The default value is 0 (no retry). |
rate_limit | Float | No | The maximum number of messages (per second) that are sent to an endpoint. The default value is 0 (no rate limiting). You can enter a value less than 1.0 to have lower rate limits. For example, if you set the value to 0.5, the appliance sends less than 1 message in every 2 seconds. |
rate_limit_requests | Integer | No | Use this along with |
rate_limit_interval | Integer (in milliseconds) | No | Use this along with |
rate_limit_reset | Integer (in epoch time) | No | Use this together with rate_limit_requests and rate_limit_interval to reset the epoch time for rate limiting. The default is 0 = not resetting the epoch time for rate limiting. You can set this to an integer between 0 and 4102437600 milliseconds. Example: If For instance, 3 messages are sent at the 1st second and 7 messages sent at the 3rd second and no more messages can be sent in the next 2 seconds, which is within 5 seconds after 3 p.m. on 10 January 2017. |
endpoint_variables | List of VARIABLE structs | No | If specified these will be accessible via the S: namespace in templates. |
inactivity_interval | Integer (in milliseconds) | No | A logout request is sent after this time interval, provided no other requests have occurred during this time period. The default is 0 = “disable.” You can set this to an integer between 0 and 2^63-1 milliseconds. |
login_template | String | No | The template that requires user login if there is no active session currently running for the endpoint. Only templates with |
logout_any_condition | Boolean | No | Specifies whether a logout request is sent, depending on whether |
logout_regexp | String | No | Any response returned by the endpoint that matches the regular expression in this field will trigger a logout request. |
logout_status_code | Integer | No | The HTPPS response status code used for the provisional response will trigger a logout request. The default is 0 = “disable.” Valid values are between 0 and 599. |
logout_template | String | No | The template that is being executed after steps are executed or after various session duration constraints are met. You must include the template name in the string. Only templates with |
requests_per_session | Integer | No | The number of requests that are sent before a logout request is sent. The default is 0 = “disable.” You can set this to an integer between 0 and 2^63-1 milliseconds. |
logout_only_at_template_end | Boolean | No | The value can be True or False. The default is False. If this is set to True, a logout request is sent only after the execution of the template has been completed to ensure that all template requests pertaining to a session are executed if that is required by the API. Therefore, it is possible to set |
session_cooldown | Integer (in milliseconds) | No | When this is set, a login request will be sent only after the amount of time set for this has been elapsed after a logout. The default is 0 = “disable.” You can set this to an integer between 0 and 2^63-1 milliseconds. |
session_duration | Integer (in milliseconds) | No | The time interval after which a logout request is sent unconditionally after a login. For example, if you sent this to 150 milliseconds, after a login, a logout will be sent after 150 milliseconds whether there is current traffic or not. The default is 0 = “disable.” You can set this to an integer between 0 and 2^63-1 milliseconds. |
wapi_rate_limit | Float | No | Independent of the endpoint rate limiting, use this for persistent WAPI requests only. The maximum number of messages (per second) that are sent to an endpoint. The default value is 0 (no rate limiting). You can enter a value less than 1.0 to have lower rate limits. For example, if you set the value to 0.5, the appliance sends less than 1 message in every 2 seconds. The default is 0 = “disable.” You can set this to an integer between 0 and 100000. |
wapi_rate_limit_requests | Integer | No | Independent of the endpoint rate limiting, use this for persistent WAPI requests only. Use this along with the |
wapi_rate_limit_interval | Integer (in milliseconds) | No | Independent of the endpoint rate limiting, use this for persistent WAPI requests only. Use this along with the |
wapi_rate_limit_reset | Integer (epoch time) | No | Independent of the endpoint rate limiting, use this for persistent WAPI requests only. Use this to reset the epoch time for rate limiting. The default is 0 = not reseting the epoch time for rate limiting. You can set this to an integer between 0 and 4102437600 milliseconds. |
...
- Template error handling is active only if the severity level for logging is set to Debug, otherwise error handling is disabled and the server continues to execute a template even if the template tries to access nonexistent variables or perform invalid operations such as trying to increment a STRING variable. For information about setting the severity level for logging, see Configuring REST API Endpoints see Configuring Outbound Endpoints. If you have disabled template error handling, then accessing any nonexistent variables will return an empty string and invalid operations are not executed.
- Matching a regular expression is performed un-anchored. If anchoring is required, you must add the characters ^ and/or $ to the respective regular expression.
- For outbound notifications, only template instances are considered. Template instances are constructed from action templates as well as template instance variables in the template. You may configure these variables through Grid Manager when a specific template is associated to an event.
...
Note: Set the "wapi" field to send WAPI requests to the Grid Master using available event data. For example, you can add or modify extensible attributes of a NIOS object at the time when the object is being synchronized. If you include the "wapi" field in a step, you must enable WAPI integration by entering the WAPI login username and password while configuring the endpoint. Otherwise, the WAPI step will fail due to an authorization error. For information about how to configure endpoints, see Configuring REST API Outbound Endpoints.
...
Variable | Type | Mandatory | Sub | Description |
|---|---|---|---|---|
name | String | Yes | No | Used to refer to the steps used in the execution of the template. |
operation | ENUM | Yes | No | The valid value can be one of the following: GET, POST, DELETE, PATCH, PUT, SLEEP, CONDITION, NOP, VARIABLEOP, DXL_EVENT_SEND, or SERIALIZE. If you specify SLEEP, only timeout is supported, where timeout is the sleep length in seconds. If you specify NOP, only variable operations are performed, and only body/body_list is supported. If you specify VARIABLEOP, you must use the VARIABLE struct within your steps that are executed in sequence. See VARIABLE Struct for the supported fields. If you specify SERIALIZE, see SERIALIZE Struct for the supported variables. |
condition | CONDITION Struct | No | Applicable only if the operation is set to CONDITION. | |
timeout | String | No | Yes | If specified, overrides the endpoint configuration value (it is useful if the template is slow during execution). Note that the timeout value is invalid for NOP. Since the timeout variable is a string, you can substitute the variable in individual steps. |
transport | TRANSPORT Struct | No | Path only | |
result | List of RESULT Structs | No | No | If not present, you can assume 200, everything else is a failure. If not specified, the steps are executed sequentially. This is not valid for SLEEP, NOP, or CONDITION variables. |
parse | ENUM | No | No | If specified, the output of the server will be parsed. The valid value is one of the following: JSON, REGEXLINE, REGEXMULTILINE, REGEX, XMLA, or XML. Infoblox recommends that you use XMLA instead of XML for parsing. Ensure that you see Result Parsing for details. |
parse_regex | String | No | No | You can set one of the following: REGEX, REGEXLINE, or REGEXMULTILINE |
parameters | List of PARAMETERS | No | Value only | These are URI parameters. |
headers | Dictionary of name/value pairs | No | Yes | This is sent as HTTP headers. The name space substitution is supported only for value. Note that assigning to the H: name space also sends headers. |
override_headers | Boolean | No | No | If specified, only these headers and H: name space headers are sent instead of template headers. |
body | String | No | Yes | This is applicable only for POST, PATCH, DXL_EVENT_SEND, and PUT requests as well as NOP operations. It will be sent as the body of the request. Note that name space substitution is supported. |
body_list | List of strings | No | Yes | This is an alternative to the body. If specified, the strings in the list will be joined before sending it. Any leading or trailing whitespace is removed. |
no_connection_debug | Boolean | No | No | The valid value is True or False. If this is set to True even if the endpoint is set to a Debug level logging, only the body, headers, and cookies for the corresponding step will NOT be output to the debug log. Only explicit DEBUG calls will be displayed. This is generally used in login templates to avoid usernames and passwords from being logged to the log files in plain text. |
variable_ops | List of VARIABLEOP structs | No | No | |
serializations | List of SERIALIZE structs | No | No | |
comment | String | No | No | Adds information about the steps. |
| wapi | String | No | No | The WAPI version. When this is set, the username and password (auth username and auth password) specified for the endpoint are ignored for WAPI related steps only. Other steps still use the configured auth username and auth password. All WAPI requests are sent to the Grid Master IP. The path of the requests is /wapi/[version]/ with the appended path as specified in the step. The override path option as well as any path configured in the session management template will have no effect. |
| wapi_quoting | ENUM | No | No | The valid value is one of the following: JSON or XML. If this is not specified, it is set to JSON. The default is JSON. JSON and XML parsing performs as usual for WAPI. |
| dxl_topic | String | No | Path only | The DXL topic that is used to send data by DXL. |
...
Format operations will function like other operations if an error occurs, but the variable is not modified. However, the error can be ignored if the log setting is not set to Debug. For information about how to set the logging level, see Configuring REST API Outbound Endpoints.
The following are some examples of using XC operations to increment and decrement IP address strings, create a network range, or remove a specific IP address.
...
- For namespace {'L':{'ip_str': '1.2.3.4'}}, an evaluating variable "${XC:INC:{L:ip_str}}" results in {'L':{'ip_str': '1.2.3.5'}} and an evaluating variable "${XC:DEC:{L:ip_str}}" results in {'L':{'ip_str': '1.2.3.3'}}.
- The same goes for IPv6 addresses. For namespace {'L':{'ip_str': '2001:db8::2'}}, an evaluating variable "${XC:INC:{L:ip_str}}" results in {'L':{'ip_str': 2001:db8::3'}}, and an evaluating "${XC:DEC:{L:ip_str}}" results in {'L':{'ip_str': '2001:db8::1'}}.
...
Items in the list are iterated one by one upon execution of any REMOVE command. The first argument of the REMOVE* command is the variable specification that contains an IP address. The second argument is the variable with the list of ranges or hosts. If the item is ‘range’, then the specified IP address is deleted from the range. Execution of any REMOVE command may result in no range, one range or two ranges that do not contain any specified IP addresses. The IP addresses specified in non-range items and ranges with different IP addresses are ignored.
The XC:REMOVEIP command specifies the single IP address as string (for example, ‘1.2.3.4’ or ‘2001:db8:ce4::42’).
The XC:RMEOVERANGE command specifies the set of IP addresses as Rapid7 range.
The XC:REMOVENET command specifies the set of IP addresses as network string.
If the first argument denotes an incorrect IP address (range or network respectively), the template execution is stopped and an error is generated for DEBUG mode, and nothing happens for non-DEBUG mode.
Evaluating IP Address in a Range or Network
Use the XC:IS_IP_IN operation to validate if an IP address is in the range and network. This operation should be specified as follows: ${XC:IS_IP_IN:{“var_with_IP”}:{“var_with_net_or_range”}} where IP address is a string such as ‘1.2.3.4’ or ‘2001:db8:ce4::42’.
Having the L namespace as:
...
The E: event name space is populated with variables from the event. For performance reasons, only the variables referred in the template will be available in the name space. This means that if the template is changed and if a new variable is added, it might take some time for the changes to be propagated to all the Grid members and the new variable to be available in future template executions.
You can use event_type in an action template to specify the following supported event types: RPZ, LEASE, TUNNEL, NETWORK_IPV4, NETWORK_IPV6, RANGE_IPV4, RANGE_IPV6, FIXED_ADDRESS_IPV4, FIXED_ADDRESS_IPV6, HOST_ADDRESS_IPV4, HOST_ADDRESS_IPV6, and SESSION. Note that SESSION is used only for the login and logout events for the session management templates. For information about action templates, see Creating Action Templates ; and for information about session management templates, see Creating Session Management Templates.
The following tables list the supported variables by event type:
...
NIOS Field Name | Template Variable Name | Filter | Enriched Data | Comment |
|---|---|---|---|---|
Timestamp | timestamp (ISO 8601 format) | When the event occurs | ||
Infoblox Member IP | member_ip | Infoblox member IP (VIP or LAN1) that has generated the event. | ||
Infoblox Member Name | member_name | |||
WAPI object reference | _ref | |||
Comment | comment | |||
Disable | disable | equals | Boolean | |
Extensible Attributes | extattrs | Dictionary of extensible attributes | ||
|
| equals, contained in |
| |
network_view | network_view | contains, equals, begins with, ends with | String | |
Members | members | |||
MS AD User Data | ms_ad_user_data | |||
Comment | comment | |||
network_container | network_container | |||
options | options | |||
unmanaged | unmanaged | |||
Event Type | event_type | equals | RPZ LEASE TUNNEL NETWORK_IPV6 RANGE_IPV4 RANGE_IPV6 FIXED_ADDRESS_IPV4 FIXED_ADDRESS_IPV6 HOST_ADDRESS_IPV4 HOST_ADDRESS_IPV6 | SESSION is used for the login and logout events for the session management templates. |
Table 45.17 Variables for DB Object Change Event - DHCP Range IPv4
...