CLI Workflow Queries

Where traffic queries provide insight into traffic conditions in your network, workflow queries allow you to identify how Director is reacting to that traffic. You can examine currently active workflows, query for current or historic trigger records, examine a trigger in more detail, or manually test individual actions or workflows.

Active Workflows

Running show active-workflows will display all entities with a currently active workflow:

# show active-workflows
   Group     |         Zone          |      IP      | Workflow
-------------+-----------------------+--------------+---------
0 - 6wind3   | 7045 - Director_test1 | 10.60.200.14 | Script  
757 - 6wind1 | 7041 - 1              | 10.60.200.10 | Script  
758 - 6wind2 | 7042 - 2              | 10.60.200.11 | Script  
759 - 6wind3 | 7043 - 3              | 10.60.200.12 | Script  
760 - 6wind4 | 7044 - 4              | 10.60.200.13 | Script

This gives immediate feedback on whether or not Director is reacting to any network events. The Group and Zone columns will display the group or zone ID followed by a dash and then the group or zone name. If an IP is listed, the workflow was initiated either by a per-host trigger or a manual start on a specified host. If no IP is listed, it was either a per-zone trigger or a manual start on a specified zone. For more details, query further using the show triggers commands.

Groups and Zones

As a convenience, you can run show group or show zone queries to check where it sits in rWeb's group and zone hierarchy. This can help to see if a mapping could be causing a workflow to affect a given group or zone:

# show group
<Group Name>: All or part of a Group Name
<Group ID>: Group ID

# show zone
<Zone Name>: All or part of a Zone Name
<Zone ID>: Zone ID

If specifying a name (use quotes if the name contains spaces), the CLI will display all matching possibilities. Groups will display their inheritance from the Default Group (with an ID of 0) down to themselves. Zones will also show this information for the group that currently owns that zone. By way of example:

info

The Default Group has been renamed to "6wind3" here. While it is no longer named "Default", note its ID is still 0.

# show zone 7042
----
Zone ID: 7042
Zone Name: 2
Group tree:
0 - 6wind3
┗ 758 - 6wind2

Triggers

You can query for current or historical triggers with filter clauses. Without any specified clauses, running show triggers will default to showing all currently active triggers:

# show triggers
             Trigger ID              |   Type    | Workflow | Group | Zone |     Host     |     Start Time      | End Time
-------------------------------------+-----------+----------+-------+------+--------------+---------------------+---------
d80fb29c-7300-4512-be19-d931dc28997d | host-rate | Script   | 757   | 7041 | 10.60.200.10 | 2024-01-03 18:25:39 | -       
cfde97ef-1d88-4573-aacf-3dc1a5f26997 | host-rate | Script   | 0     | 7045 | 10.60.200.14 | 2024-01-03 18:25:39 | -       
177794f3-7005-4826-88fe-99ad1e2cf7b1 | host-rate | Script   | 758   | 7042 | 10.60.200.11 | 2024-01-03 18:25:39 | -       
ddce4b69-50f9-463a-9c96-a5d0fe9115dc | host-rate | Script   | 759   | 7043 | 10.60.200.12 | 2024-01-03 18:25:39 | -       
229986d4-d450-46b2-b1ee-9c9641ab5c74 | host-rate | Script   | 760   | 7044 | 10.60.200.13 | 2024-01-03 18:25:39 | -   

The displayed information is:

• Trigger ID: The unique UUID for this trigger. Can be used with trigger detail for more information.
• Type: The type of trigger. This will be one of zone-rate, host-rate, zone-always-on, host-manual, or zone-manual. The first three are configured workflow trigger types. The latter two are initiated by the user, as described in the manual section.
• Workflow: The name of the workflow associated with the trigger. If this is blank, it will be a result of a user manually starting an action (not a workflow).
• Group: The owning group, showing the group's ID.
• Zone: The owning zone, showing the zone's ID.
• Host: The destination IP affected by this trigger. If blank, it means it was a zone based trigger (i.e. of type zone-rate, zone-always-on, or zone-manual).
• Start Time: The time in UTC when this trigger was activated.
• End Time: The time in UTC when this trigger was deactivated. If blank, the trigger is still active and ongoing.

Trigger Clauses

You can modify trigger searches with a variety of clauses:

# show triggers
from: Triggers ended after timestamp
to: Triggers started before timestamp
at: Triggers active at timestamp (default now)
workflow: For workflow name
group: For group ID
zone: For zone ID
host: For host address
type: Limit to triggers with a specific cause
action: With triggered action
<enter>: Query events

In general, clauses do not need to be strictly ordered but can be used in whatever order makes sense to you. However, individual clauses expect specific syntax and should alert you if you violate their rules. The clauses here are in many ways distinct from those used in traffic queries and may not work in the same way, even if they use identical keywords.

info

By default searches are looking for currently active triggers. If you are looking for historical records, make sure to either bound a time range using from and to or specify a specific point in time using at.

From

The from clause modifies the query to only use data after this point in time. This can be set as either a specific datetime using an ISO formatted timestamp, or calculated as an offset from the time the query is executed (using a single unit, either days, hours, or minutes). Mutually exclusive with the at clause.

# show triggers from
<date>: ISO Format Timestamp (2000-01-01T00:00:00)
<n> days ago
<n> minutes ago
<n> hours ago

To

The to clause modifies the query to only use data before this point in time. This can be set as either a specific datetime using an ISO formatted timestamp, or calculated as an offset from the time the query is executed (using a single unit, either days, hours, or minutes). Mutually exclusive with the at clause.

# show triggers to
<date>: ISO Format Timestamp (2000-01-01T00:00:00)
<n> days ago
<n> minutes ago
<n> hours ago

At

The at clause modifies the query to retrieve triggers active at a specific point in time. This can be set as either a specific datetime using an ISO formatted timestamp, or calculated as an offset from the time the query is executed (using a single unit, either days, hours, or minutes). Mutually exclusive with the from and to clauses. Implictly always specified as the current time if not using either of those clauses or a specific value.

Default: Now

# show triggers at
<date>: ISO Format Timestamp (2000-01-01T00:00:00)
<n> days ago
<n> minutes ago
<n> hours ago

Workflow

The workflow clause modifies the query to retrieve triggers with the same workflow name. This requires an exact match. If your workflow name has spaces in it, use double quotes when entering the name.

# show triggers workflow
<workflow>: Workflow name

Group

The group clause modifies the query to retrieve triggers matching that group ID. This requires specifying the group ID (not the name).

# show triggers group
group: For group ID

Zone

The zone clause modifies the query to retrieve triggers matching that zone ID. This requires specifying the zone ID (not the name).

# show triggers zone
zone: For zone ID

Type

The type clause modifies the query to retrieve triggers of the specified type. This can help separate which triggers are a result of network events, always-on behavior, or user initiated behavior.

# show triggers type
zone-rate: Triggers caused by zone rate
host-rate: Triggers caused by host rate
zone-always-on: Triggers caused by always-on zones
host-manual: Triggers caused by manual host action
zone-manual: Triggers caused by manual zone action.

Action

The action clause modifies the query to retrieve triggers whose workflow contains that action. This requires an exact match. If your action name has spaces in it, use double quotes when entering the name.

# show triggers action
<action>: Action name

Trigger Detail

Use show trigger-detail <UUID> to get all information about the sepcified trigger. In our test example here it shows that this trigger activated because the host exceeded our (contrived) 1 packet per second threshold:

# show trigger-detail d80fb29c-7300-4512-be19-d931dc28997d
Trigger ID: d80fb29c-7300-4512-be19-d931dc28997d
Type: host-rate
Workflow: Script
Group: 757 - 6wind1
Zone: 7041 - 1
Host: 10.60.200.10
Reasons: InPackets 10277 >= 1
Start Time: 2024-01-03 18:25:39.808435+00:00

Manual Operations

During setup, or when implementing new workflows, you may want to individually test that the workflow or its component actions are working as expected. Using the CLI you can directly start workflows or actions without needing to satisfy a normal trigger condition with the manual command:

# manual
start: Start an operation manually
stop: Stop a previously started manual operation
zone: Perform operation on this zone
host: Perform operation on this host
action: Perform this action
workflow: Perform this workflow
<enter>: Manually start or stop operations on a target

Loosely, a manual command follows the format manual <verb> <operation> <target> (clauses can be in any order) where:

• verb: start or stop
• operation: action or workflow followed by the action/workflow name
• target: host followed by IP or zone followed by zone ID

Starting a workflow or action will immediately trigger the specified operation against the target (either zone or host), and persist until stopped by a manual stop of the same operation on the same target. Manual stops will only stop a previously started manual operation, but have no impact on workflows started by host-rate, zone-rate, or zone-always-on triggers. Started operations will persist through any configuration reloads (stopping and restarting any relevant actions if they are impacted by the new configuration) but will not persist through system shutdown. Post reboot, any manual operations will need to be started up again.