🎉 hyperglass 2.0 is here! This documentation is still in development, though.
Configuration
Directives File

What is a directive?

A directive is a defined configuration for one or more commands to run on a device. For example, a BGP Route query is a built-in directive. A directive defines:

  • What command (or commands) to run on the device
  • Type of UI field, text input or select
  • If the field can accept multiple values
  • Help information to show about the directive
  • Validation rules

Each directive has the following options:

ParameterTypeDefault ValueDescription
nameStringDisplay name of the directive.
rulesList of RulesList of rule configs
fieldMappingMapping/dict of fields config
infoStringFile path to markdown-formatted help information about the directive.
pluginsList of StringsList of plugin names to use with this directive.
groupsList of StringsList of names by which directives are grouped in the UI.
multipleBooleanfalseCommand supports receiving multiple values. For example, Cisco IOS’s show ip bgp community accepts multiple communities as arguments.
multiple_separatorString" "String by which multiple values are separated. For example, a list of values [65001, 65002, 65003] would be rendered as 65001 65002 65003 for when the command is run.

Rules

A rule is a way of saying “if a query target matches the rule’s conditions, run this command”.

ParameterTypeDefault ValueDescription
conditionStringRegular expression to match or IP prefix in which the value being evaluated must be contained.
actionStringpermitpermit or deny the directive target when this rule is matched.
commandsList of StringsCommands to run when this rule matches. {target} is replaced with the query target.

IP Rule

ParameterTypeDefault ValueDescription
geNumber0Prefix length greater than defined will be matched.
leNumber32,12832 for IPv4 evaluations, 128 for IPv6 evaluations. Prefix length less than defined will be matched.
allow_reservedBooleanfalseAllow reserved (RFC1918, RFC5735, RFC5737, etc.) addresses to pass validation.
allow_unspecifiedBooleanfalseAllow unspecified addresses (0.0.0.0 ::) to pass validation.
allow_loopbackBooleanfalseAllow loopback addresses (127.0.0.0/8 ::1) to pass validation.

Examples

Require IPv4 Queries between /8 and /24
directives.yaml
your-directive:
    name: IP Route
    rules:
        - condition: 0.0.0.0/0
          ge: 8
          le: 24
          command: "show ip route {target} {mask}"

Given a query target of 198.18.0.0/15, the command run on the device would be:

show ip route 198.18.0.0 255.254.0.0
Deny a Specific Prefix
directives.yaml
your directive:
    name: BGP Route
    rules:
        - condition: "192.0.2.0/24"
          action: deny
        - condition: "0.0.0.0/0"
          command: "show ip bgp {target}"

In this example, a query of any IP address or prefix contained within 192.0.2.0/24 will result in an error.

Run Multiple Commands
directives.yaml
your-directive:
    name: BGP Communities
    rules:
        - condition: "65000:[0-9]+"
          commands:
              - "show route table inet.0 community {target} detail"
              - "show route table inet6.0 community {target} detail"

In this example, a query of 65000:1 would result in the following commands being sent to the device:

show route table inet.0 community 65000:1 detail
show route table inet6.0 community 65000:1 detail

The output for both commands will be shown as the query result.

Regex Validation

To validate input by regex pattern, just specify a regex pattern as the condition

directives.yaml
your-directive:
    name: DNS Query
    rules:
        - condition: '^.+\.yourdomain\.com$'

No Validation

directives.yaml
your-directive:
    name: IP Route
    rules:
        - condition: null
          command: show ip route {target}

In this example, any query would pass, regardless of query input. For instance, if a user selected this directive/query type and queried your mom, the real command sent to the device will be:

show ip route your mom

Fields

Text Input

ParameterTypeDefault ValueDescription
descriptionStringField description, displayed as a label or help text.
validationStringRegex pattern to validate text input.

Select

ParameterTypeDefault ValueDescription
descriptionStringField description, displayed as a label or help text.
optionsList of Options

Options

Each select option uses the following schema:

ParameterTypeDefault ValueDescription
descriptionStringField description, displayed as a label or help text.
nameStringIf specified, will be used as the option’s display name.
valueStringOption value sent to the device.

Examples

Example of a text directive expecting a string value matching a regex pattern:

directives.yaml
your-directive:
    name: IP Route
    rules:
        - condition: null
          command: show ip route {target}
    field:
        validation: '[0-9a-f\.\:]+'

Example of a select directive:

directives.yaml
your-directive:
    name: BGP Community
    rules:
        - condition: null
          command: show ip bgp community {target}
    field:
        options:
            - value: "65001:1"
              description: Provider A Routes
            - value: "65001:2"
              description: Provider B Routes