Adding Devices

Adding Devices

To add, as an example, a Cisco router, add the following to your devices.yaml, with the relevant details changed for your device:

devices.yaml
routers:
- name: New York City, NY
address: 10.0.0.1
network:
name: production
display_name: AS65000
credential:
username: username
password: password
port: 22
nos: cisco_ios
vrfs:
- name: global
default: true
ipv4:
source_address: 192.0.2.1
ipv6:
source_address: 2001:db8::1

All Device Parameters

ParameterTypeDescription
* nameStringDevice's user-facing name.
* addressStringDevice management hostname or IP address.
* networkStringNetwork Configuration
* portIntegerTCP port used to connect to the device. 22 by default.
* nosStringNetwork Operating System.
Must be a supported platform.
structured_outputBooleanDisabled output parsing to structured data.
*credentialDevice Credential Configuration
*vrfsDevice VRF Configuration
proxySSH Proxy Configuration
sslSSL Configuration for devices using hyperglass-agent.

network

A network is only used for grouping. For example, if your network contains more than one ASN, you might want to group each device separately. Currently, you must define a network on each device.

ParameterTypeDescription
* nameStringThe network's name. This name is only used by hyperglass internally.
* display_nameStringThe network's use-facing name.

proxy

Any device that uses SSH (see platforms for breakdown) can be accessed through an intermediary SSH "proxy". The process is nearly identical to using local SSH tunneling, e.g. ssh -L local_port:remote_device:remote_port username@proxy_server -p proxy_port.

ParameterTypeDefaultDescription
* nameStringProxy hostname.
* addressStringProxy management hostname or IP address.
* credentialProxy Credential Configuration
nosString'linux_ssh'Proxy's network operating system.
Must be a supported platform.
portInteger22TCP port user to connect to the proxy.
important

Currently, only linux_ssh has been tested and validated for use as an SSH proxy.

credential

While all devices require a credential mapping, the credential values themselves may be used in different ways depending on the device NOS. For SSH devices, the credential is used as a typical SSH username and password.

For HTTP devices (i.e. devices using hyperglass-agent), the username is ignored and the password is used as a secret for JSON Web Token encoding/decoding.

ParameterTypeDescription
* usernameStringUsername
passwordStringPassword
Passwords will never be logged
keyPathPath to SSH Private Key

To use SSH key authentication, simply specify the path to the SSH private key with key:. If the key is encrypted, set the private key's password to the with the password: field, and hyperglass will use it to decrypt the SSH key.

ssl

HTTP devices may optionally use SSL for the connection between hyperglass and the device. This is disabled by default, which means devices will use unencrypted HTTP by default.

If SSL is enabled, the public key of the device must be provided in the form of an accessible absolute file path. With SSL enabled and a valid certificate specified, every connection to the device will use HTTPS in addition to payload encoding with JSON Web Tokens.

ParameterTypeDescription
enableBooleanEnable or disable the use of SSL.
If enabled, a certificate file must be specified (hyperglass does not support connecting to a device over an unverified SSL session).
* certStringAbsolute path to agent's public RSA key.

vrfs

The VRFs section is a list of available VRFs for a given device. Each VRF may be configured with the following fields:

ParameterTypeDescription
* nameStringThe VRF's name, as known by the device.
hyperglass sends this field to the device for queries, so it needs to match the device's configuration. If this is the default/global routing table on the device, this value isn't sent to the device.
display_nameStringThe VRF's user-facing name. This field's value is visible in the UI.
If this is not specified, hyperglass will try to create a "pretty" display name based on the name field.
defaultBooleanIndicate that this VRF is the device's default/global routing table (more specifically, that it does not require specifying the VRF name when running commands).
If this is set to true, the ipv4_default/ipv6_default command sets. If set to false, the ipv4_vpn/ipv6_vpn command sets will be used.
infoPer-VRF Contextual Help Configuration
ipv4VRF's IPv4 Configuration
ipv6VRF's IPv6 Configuration

ipv4

May be set to null to disable IPv4 for this VRF, on the parent device.

ParameterTypeDescription
* source_addressStringDevice's source IPv4 address for directed queries (ping, traceroute).
force_cidrBooleantrue
access_listIPv4 Access List Configuration

ipv6

May be set to null to disable IPv6 for this VRF, on the parent device.

ParameterTypeDefaultDescription
* source_addressStringDevice's source IPv6 address for directed queries (ping, traceroute). This address must be surrounded by quotes. Ex. "0000:0000:0000::"
force_cidrBooleantrueConvert IP host queries to actual advertised containing prefix length
access_listIPv6 Access List Configuration
note

The force_cidr option will ensure that a BGP Route query for an IP host (/32 IPv4, /128 IPv6) is converted to its containing prefix. For example, a query for 1.1.1.1 would be converted to a query for 1.1.1.0/24. This is because not all platforms support a BGP lookup for a host (this is primary a problem with IPv6, but the option applies to both address families).

When force_cidris set to true, hyperglass will perform a lookup via the bgp.tools whois API to get the advertised prefix for an IP host.

access_list

The access_list block can be thought of like a prefix-list from Cisco IOS. It is a list of rules, where the first matching rule is the action executed.

ParameterTypeDefaultDescription
* networkStringThis rule's IPv4 or IPv6 base prefix
actionString'permit'This rule's action. Must be permit or deny
geInteger0To match this rule, the target prefix must be greater than or equal to ge
leInteger32 | 128To match this rule, the target prefix must be less than or equal to le

info

Each VRF may enable, disable, or customize the contextual help menu for each enabled query type. The following parameters may be defined under any query type:

ParameterTypeDefaultDescription
enableBooleantrueEnable or disable the help menu for this command.
fileStringPath to a plain text or markdown file containing customized help information for this command.
paramsObjectAny arbitrary key/value pairs where the value will replace any occurrences of the key when wrapped in braces (e.g. {key})

For example:

devices.yaml
routers:
- name: router01
vrfs:
- name: demo_vrf
info:
bgp_route:
enable: true
file: /etc/hyperglass/customer_bgp_route.md
params:
vrf_name: Customer A
ping:
enable: false
bgp_community:
enable: true
file: /etc/hyperglass/customer_bgp_community.md
params:
vrf_name: Customer A
community: "65000"

Telnet

Telnet support is provided via the underlying device connection handling framework, Netmiko. To connect to a device via serial, add the suffix _telnet to the device's nos value and set the port value to 23.

For example:

devices.yaml
routers:
- name: router01
nos: cisco_ios_telnet
port: 23
...

Full Example

Below is a full example with nearly every available knob turned:

devices.yaml
routers:
# HTTP/hyperglass-agent device
- name: HTTP Router
address: 192.0.2.1
network:
name: primary
display_name: AS65000
credential:
username: madeup
password: txeTTIqwhKSJi4V3tefXQASf5AyGZ6cPsycS9nYLpKk
ssl:
enable: true
cert: /etc/hyperglass/certs/router01.pem
port: 8080
nos: frr
vrfs:
- name: global
default: true
ipv4:
source_address: 192.0.2.1
access_list:
- network: 10.0.0.0/8
action: deny
ge: 8
le: 32
- network: 0.0.0.0/0
action: permit
le: 24 # Only allow /24 or smaller prefixes
ipv6:
source_address: 2001:db8::1
access_list:
- network: ::/0
action: permit
proxy: null
# SSH/netmiko device
- name: SSH Router
address: 10.0.0.1
network:
name: primary
display_name: AS65000
credential:
username: user
password: pass
port: 22
nos: cisco_ios
vrfs:
- name: global
default: true
ipv4:
source_address: 192.0.2.2
access_list:
- network: 10.0.0.0/8
action: deny
ge: 8
le: 32
- network: 0.0.0.0/0
action: permit
ipv6:
source_address: 2001:db8::2
access_list:
- network: ::/0
action: permit
le: 64 # Only allow /64 or smaller prefixes
- name: special_customer
display_name: Customer Name
ipv4:
source_address: 172.16.0.1
access_list:
- network: 172.16.0.0/16
action: allow
ipv6: null # disable IPv6 for this VRF
info:
bgp_route:
file: /etc/hyperglass/help/customer_bgp_route.md
params:
customer_name: Customer Name
proxy:
name: jump_server
address: 10.0.1.100
port: 22
credential:
username: user
password: pass
nos: linux_ssh

YAML Anchors & Aliases

If you have a lot of devices with shared configuration parameters, you may want to look into YAML Anchors and Aliases. If you've never used them before, they can be pretty weird looking at first read. Atlassian has a pretty decent guide.

Here's an example of using this to share two sets of credentials among multiple devices:

devices.yaml
my_credentials:
- credential: &credential1
username: madeup1
password: gY018mR4gx4sVqc0
- credential: &credential2
username: madeup2
password: 0eMEJ4ZpB6ofkiIF
routers:
- name: router01
credential: *credential1
- name: router02
credential: *credential2
- name: router03
credential: *credential1
- name: router04
credential: *credential2
important

Nothing other than the routers key is read by hyperglass. In the above example, my_credentials is just an arbitrary list of mappings, is completely optional, and can be named whatever you want.

For a more complex example, here's an example of how to use YAML aliases & anchors to share a common VRF configuration among multiple devices, while overriding key variables such as the source_address key:

devices.yaml
my_vrfs:
- &default
name: global
default: true
display_name: Global
ipv4:
access_list: &default_ipv4_acl
- network: 10.0.0.0/8
action: deny
- network: 192.168.0.0/16
action: deny
- network: 172.16.0.0/12
action: deny
- network: 0.0.0.0/0
action: permit
ge: 8
le: 24
ipv6:
access_list: &default_ipv6_acl
- network: ::/0
action: permit
ge: 32
le: 64
- &customer_a
name: customer_a
default: false
display_name: Customer A
ipv4:
access_list: &customer_a_ipv4_acl
- network: 10.0.0.0/8
action: permit
- network: 0.0.0.0/0
action: deny
ipv6: null
routers:
- name: router01
vrfs:
- <<: *default
ipv4:
source_address: 192.0.2.1
access_list: *default_ipv4_acl
ipv6:
source_address: 2001:db8::1
access_list: *default_ipv6_acl
- <<: *customer_a
ipv4:
source_address: 10.0.0.1
access_list: *customer_a_ipv4_acl
- name: router02
vrfs:
- <<: *default
ipv4:
source_address: 192.0.2.2
access_list: *default_ipv4_acl
ipv6:
source_address: 2001:db8::2
access_list: *default_ipv6_acl
- <<: *customer_a
ipv4:
source_address: 10.0.0.2
access_list: *customer_a_ipv4_acl