...
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.
...
- 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:
...