Interface Workflows

An interface-workflow is a set of triggers and actions that will occur if any of those triggers are met. The interface-sets configurations will map interfaces from sampled network devices to interface-workflows in order to check network trigger conditions. When an interface-workflow is triggered, it will attempt to start all specified actions, stopping them when the trigger condition is no longer met or according to more advanced conditions.

Interface Workflows

# Interface Workflows must have a unique identifier for an interface set to
# refer to. They are distinct from `[workflows]`
[interface-workflows.An-Interface-Workflow]

# When this workflow is triggered, -all- of the following
# actions will be evaluated.
actions = [
    "BgpExample",
    "BgpFlowspecExample"
]

# If set, all actions triggered by this workflow will be in no-operation mode.
# Actions will be logged and recorded but not actually executed.
# Optional, default false
no-op = true

# How often to recheck an interface after running traffic analysis.
# Interface Workflows perform live analysis on traffic that is contributing
# the most load to the selected interfaces. Unlike normal Workflows, it will
# retest and potentially start new actions on different addresses, but the
# trigger is still based on the underlying interface.
# Optional, defaults to 5 minutes.
poll-time = "5 minute"

# Triggers must be met continuously for this entire duration of time
# before any action will be taken.
# Optional. See `Duration` below.
min-trigger-time = "1 minute"

# Actions are guaranteed to run for at least this amount of time.
# Can help prevent flapping.
# Optional. See `Duration` below.
min-action-time = "1 minute"

# Triggers must be unmet continuously for this entire duration of time
# before any previous action(s) will be withdrawn/stopped.
# Can also prevent flapping.
# Optional. See `Duration` below.
min-untriggered-time = "1 minute"

Interface Workflow Keys

At a minimum, each interface-workflow section should have a unique identifier, and zero or more actions that it should start (as shown above). There are also a number of optional flags that can be set to change interface-workflow behavior:

no-op: A boolean flag that defaults to false, but when set forces all actions triggered by the workflow into no-operation mode. All of the action starts and stops as a result of this interface-workflow will only log when an action would be started or stopped, but it won't actually perform the action.
poll-time: An optional duration value that represents how long the interface-workflow will wait before running another traffic analysis. Unlike other workflows, an interface-workflow is specific to a defined network interface and so may observe different prefix behavior over time, so an interface-workflow can be triggered (by the interface) but launch new actions periodically (based on observed traffic destinations). If an interface becomes untriggered it will stop polling until either the interface-workflow finishes completely or the interface again meets the threshold for being triggered. actions that are initiated by a repoll will include that in their list of reasons.
min-trigger-time: An optional duration value that represents how long a trigger must be (continuously) exceeded before the related actions are started. This can help prevent starting potentially expensive network redirect events for transient blips in traffic levels.
min-action-time: An optional duration value that indicates the minimum amount of time an action should be in effect before stopping it. If not set, the related actions will be stopped as soon as the associated interface-workflow triggers fall below their threshold. Similar to min-trigger-time, you may not want to withdraw a traffic announcement just to make it again immediately based on transient network conditions.
min-untriggered-time: An optional duration value that imposes a condition on stopping an action. This value sets the minimum amount of time the workflow must be untriggered (uncontinuously) before the action is stopped.

In other words, no-op can be used to test what actions would be started based on your interface-sets and triggers (without actually doing those actions), min-trigger-time can be used to affect when an action would start, and min-action-time and min-untriggered-time can be used to affect when an action would stop. poll-time affects how often an interface will be evaluated to start new actions.

info

If both min-action-time and min-untriggered-time are set, both conditions must be satisfied before the associated actions will be stopped. That is, the action must have been active for at least the duration set by min-action-time and the associated triggers for the workflow must have been below threshold (continuously) for the duration set by min-untriggered-time.

Top Destination Triggers

# Zero or more top destination triggers for the interface workflow.
# If -any- of these triggers are met, then the workflow actions will be started.
# These triggers are activated by exceeding the configured limit value, but then
# further live traffic analysis is run on the interface exceeding that limit to
# determine the top destinations, which are then used for actions.
[[interface-workflows.An-Interface-Workflow.top-dest-trigger]]
# Trigger type. See full list below.
type = "bits-per-second"

# Start interface analysis when this rate is exceeded.
# Can be anything described in the `Unit` special values section.
# Any bit rate trigger must be at least 1 Mbps.
limit = "200 M"

# The type of tracking to use, currently only allows "static-prefix".
# Optional, defaults to "static-prefix"
top-k-tracking = "static-prefix"

# When tracking top destinations on an interface, it will aggregate by these
# prefix lengths for IPv4 and IPv6 respectively.
# Optional, defaults to 24 for IPv4 and 48 for IPv6
ipv4-prefix-length = 24
ipv6-prefix-length = 48

# When tracking, the top results returned must collectively contribute
# to this percentage of the `limit` to be considered actionable.
# Optional, defaults to 20
significant-percentage = 20

# The number of tracking slots to reserve.
# Optional, defaults to 100
top-k = 100

# After tracking, return up to this many results.
# Optional, defaults to 5
top-k-result = 5

# This is how long live tracking analysis will run before returning results.
# Optional, defaults to `[engine.average-calculation-time]`.
# tracking-time = 5

Top Destination Trigger Keys

Zero or more interface-workflow top destination triggers (top-dest-trigger) can be set, each with a given type and a limit (using a unit value). These triggers are tested against the interfaces specified in the interface-sets associated with this interface-workflow. The full set of types is listed below, and the applicable limit values use the unit as stated in the rate trigger's name.

For interface-workflows the trigger condition is met by the associated traffic type being over the limit on a per interface basis. Once the interface is over this limit, a top-dest-trigger runs traffic analysis based on the rest of its configuration, to identify the destination prefixes that are contributing the most to traffic on that particular interface. The additional configuration for this analysis is:

top-k-tracking: An optional value indicating the type of top-k tracking to use. Currently there is only one available type, static-prefix, which is the default.
ipv4-prefix-length, ipv6-prefix-length: Optional values, indicating how to aggregate IPv4 and IPv6 addresses when tracking top destinations on an interface. Defaults to 24 for IPv4 and 48 for IPv6. This prefix length directly affects the results that will be used for action generation.
significant-percentage: An optional value indicating what percentage the top results returned must collectively contribute compared to the limit to be considered actionable. If the limit was 1M packets-per-second, the default value of 20 requires that the set of prefixes returned by tracking must exceed at least 200kpps (20% of our 1Mpps). This helps ensure results are contributed significantly to traffic on the interface and that it's not too distributed. Can not be set to 0.
top-k: When doing live interface analysis, the tracking process reserves a number of slots to use when determining the top contributors to traffic on that interface. Increasing the number of slots can increase the fidelity of the tracking at the cost of increased memory usage. In most cases this does not need to be adjusted. Optional, defaults to 100 and can not be set to 0.
top-k-results: After tracking, return up to this many results. Each result will be aggregated by the configured IPv4/IPv6 prefix-lengths, and the combined traffic of all results will exceed the significant-percentage threshold. If fewer results meet this threshold, fewer results will be returned (e.g. one /24 is 30% of our 200 Mbps limit and we are using defaults). If the top-k-result entries don't exceed this threshold, no results wil be returned for actions. Optional, defaults to 5, but can not be set to 0.
tracking-time: The time, in seconds, for long live tracking analysis will run before returning results. In most cases adjusting this will be specific to how you are exporting flows, so it defaults to the engine's average-calculation-time value as you probably will have adjusted the appropriate value there. Optional, defaults to engine.average-calculation-time.

If the interface-workflow has poll-time set, this analysis will be re-run periodically, or if the trigger is exceeded while waiting for min-untriggered-time. When polled again, if a destination prefix already had actions generated for it the interface-workflow will not start actions on that prefix again.

Top Destination Trigger Types

These trigger based on the network interfaces associated with this interface-workflow. Once an interface exceeds this trigger, analysis will be done to determine the top destination prefixes associated with the trigger.

packets-per-second
fragmented-packets-per-second
icmp-packets-per-second
tcp-packets-per-second
tcp-syn-packets-per-second
udp-packets-per-second
bits-per-second
fragmented-bits-per-second
icmp-bits-per-second
tcp-bits-per-second
tcp-syn-bits-per-second
udp-bits-per-second