salt.runners.net

NET Finder

New in version 2017.7.0.

A runner to find network details easily and fast. It's smart enough to know what you are looking for.

Configuration

  • Minion (proxy) config

    To have the complete features, one needs to add the following mine configuration in the minion (proxy) config file:

    mine_functions:
      net.ipaddrs: []
      net.lldp: []
      net.mac: []
      net.arp: []
      net.interfaces: []
    

    Which instructs Salt to cache the data returned by the NAPALM-functions. While they are not mandatory, the less functions configured, the less details will be found by the runner.

    How often the mines are refreshed, can be specified using:

    mine_interval: <X minutes>
    
  • Master config

    By default the following options can be configured on the master. They are not necessary, but available in case the user has different requirements.

    target: *

    From what minions will collect the mine data. Default: * (collect from all minions).

    expr_form: glob

    Minion matching expression form. Default: glob.

    ignore_interfaces

    A list of interfaces name to ignore. By default will consider all interfaces.

    display: True

    Display on the screen or return structured object? Default: True (return on the CLI).

    outputter: table

    Specify the outputter name when displaying on the CLI. Default: table.

    Configuration example:

    runners:
      net.find:
        target: 'edge*'
        expr_form: 'glob'
        ignore_interfaces:
          - lo0
          - em1
          - jsrv
          - fxp0
        outputter: yaml
    
salt.runners.net.find(addr, best=True, display=True)

Search in all possible entities (Interfaces, MAC tables, ARP tables, LLDP neighbors), using the following mine functions:

  • net.mac
  • net.arp
  • net.lldp
  • net.ipaddrs
  • net.interfaces

This function has the advantage that it knows where to look, but the output might become quite long as returns all possible matches.

Optional arguments:

best: True
Return only the best match with the interfaces IP networks when the saerching pattern is a valid IP Address or Network.
display: True
Display on the screen or return structured object? Default: ``True``(return on the CLI).

CLI Example:

$ sudo salt-run net.find 10.10.10.7

Output Example:

Details for all interfaces that include network 10.10.10.7/32 - only best match returned
________________________________________________________________________________________________________________________
|    Device    | Interface | Interface Description |  UP  | Enabled | Speed [Mbps] |    MAC Address    |  IP Addresses |
________________________________________________________________________________________________________________________
| edge01.flw01 |    irb    |                       | True |   True  |      -1      | 5C:5E:AB:AC:52:B4 | 10.10.10.1/22 |
________________________________________________________________________________________________________________________

ARP Entries for IP 10.10.10.7
_____________________________________________________________________________
|    Device    |     Interface     |        MAC        |     IP     |  Age  |
_____________________________________________________________________________
| edge01.flw01 | irb.349 [ae0.349] | 2C:60:0C:2A:4C:0A | 10.10.10.7 | 832.0 |
_____________________________________________________________________________
salt.runners.net.findarp(device=None, interface=None, mac=None, ip=None, display=True)

Search for entries in the ARP tables using the following mine functions:

  • net.arp

Optional arguments:

device
Return interface data from a certain device only.
interface
Return data selecting by interface name.
mac
Search using a specific MAC Address.
ip
Search using a specific IP Address.
display: True
Display on the screen or return structured object? Default: True, will return on the CLI.

CLI Example:

$ sudo salt-run net.findarp mac=8C:60:0F:78:EC:41

Output Example:

ARP Entries for MAC 8C:60:0F:78:EC:41
________________________________________________________________________________
|    Device    |     Interface     |        MAC        |       IP      |  Age  |
________________________________________________________________________________
| edge01.bjm01 | irb.171 [ae0.171] | 8C:60:0F:78:EC:41 | 172.172.17.19 | 956.0 |
________________________________________________________________________________
salt.runners.net.findmac(device=None, mac=None, interface=None, vlan=None, display=True)

Search in the MAC Address tables, using the following mine functions:

  • net.mac

Optional arguments:

device
Return interface data from a certain device only.
interface
Return data selecting by interface name.
mac
Search using a specific MAC Address.
vlan
Search using a VLAN ID.
display: True
Display on the screen or return structured object? Default: True, will return on the CLI.

CLI Example:

$ sudo salt-run net.findmac mac=8C:60:0F:78:EC:41

Output Example:

MAC Address(es)
_____________________________________________________________________________________________
|    Device    | Interface |        MAC        | VLAN | Static | Active | Moves | Last move |
_____________________________________________________________________________________________
| edge01.bjm01 |  ae0.171  | 8C:60:0F:78:EC:41 | 171  | False  |  True  |   0   |    0.0    |
_____________________________________________________________________________________________
salt.runners.net.interfaces(device=None, interface=None, title=None, pattern=None, ipnet=None, best=True, display=True)

Search for interfaces details in the following mine functions:

  • net.interfaces
  • net.ipaddrs

Optional arguments:

device
Return interface data from a certain device only.
interface
Return data selecting by interface name.
pattern
Return interfaces that contain a certain pattern in their description.
ipnet
Return interfaces whose IP networks associated include this IP network.
best: True
When ipnet is specified, this argument says if the runner should return only the best match (the output will contain at most one row). Default: True (return only the best match).
display: True
Display on the screen or return structured object? Default: True (return on the CLI).
title
Display a custom title for the table.

CLI Example:

$ sudo salt-run net.interfaces interface=vt-0/0/10

Output Example:

Details for interface xe-0/0/0
_________________________________________________________________________________________________________________
|    Device    | Interface | Interface Description |  UP  | Enabled | Speed [Mbps] | MAC Address | IP Addresses |
_________________________________________________________________________________________________________________
| edge01.bjm01 | vt-0/0/10 |                       | True |   True  |     1000     |             |              |
_________________________________________________________________________________________________________________
| edge01.flw01 | vt-0/0/10 |                       | True |   True  |     1000     |             |              |
_________________________________________________________________________________________________________________
| edge01.pos01 | vt-0/0/10 |                       | True |   True  |     1000     |             |              |
_________________________________________________________________________________________________________________
| edge01.oua01 | vt-0/0/10 |                       | True |   True  |     1000     |             |              |
_________________________________________________________________________________________________________________
salt.runners.net.lldp(device=None, interface=None, title=None, pattern=None, chassis=None, display=True)

Search in the LLDP neighbors, using the following mine functions:

  • net.lldp

Optional arguments:

device
Return interface data from a certain device only.
interface
Return data selecting by interface name.
pattern

Return LLDP neighbors that have contain this pattern in one of the following fields:

  • Remote Port ID
  • Remote Port Description
  • Remote System Name
  • Remote System Description
chassis
Search using a specific Chassis ID.
display: True
Display on the screen or return structured object? Default: True (return on the CLI).
display: True
Display on the screen or return structured object? Default: True (return on the CLI).
title
Display a custom title for the table.

CLI Example:

$ sudo salt-run net.lldp pattern=Ethernet1/48

Output Example:

Pattern "Ethernet1/48" found in one of the following LLDP details
_________________________________________________________________________________________________________________________________________________________________________________________
|    Device    | Interface | Parent Interface | Remote Chassis ID | Remote Port ID | Remote Port Description |   Remote System Name   |            Remote System Description            |
_________________________________________________________________________________________________________________________________________________________________________________________
| edge01.bjm01 |  xe-2/3/4 |       ae0        | 8C:60:4F:3B:52:19 |                |       Ethernet1/48      | edge05.bjm01.dummy.net |   Cisco NX-OS(tm) n6000, Software (n6000-uk9),  |
|              |           |                  |                   |                |                         |                        | Version 7.3(0)N7(5), RELEASE SOFTWARE Copyright |
|              |           |                  |                   |                |                         |                        |  (c) 2002-2012 by Cisco Systems, Inc. Compiled  |
|              |           |                  |                   |                |                         |                        |                2/17/2016 22:00:00               |
_________________________________________________________________________________________________________________________________________________________________________________________
| edge01.flw01 |  xe-1/2/3 |       ae0        | 8C:60:4F:1A:B4:22 |                |       Ethernet1/48      | edge05.flw01.dummy.net |   Cisco NX-OS(tm) n6000, Software (n6000-uk9),  |
|              |           |                  |                   |                |                         |                        | Version 7.3(0)N7(5), RELEASE SOFTWARE Copyright |
|              |           |                  |                   |                |                         |                        |  (c) 2002-2012 by Cisco Systems, Inc. Compiled  |
|              |           |                  |                   |                |                         |                        |                2/17/2016 22:00:00               |
_________________________________________________________________________________________________________________________________________________________________________________________
| edge01.oua01 |  xe-0/1/2 |       ae1        | 8C:60:4F:51:A4:22 |                |       Ethernet1/48      | edge05.oua01.dummy.net |   Cisco NX-OS(tm) n6000, Software (n6000-uk9),  |
|              |           |                  |                   |                |                         |                        | Version 7.3(0)N7(5), RELEASE SOFTWARE Copyright |
|              |           |                  |                   |                |                         |                        |  (c) 2002-2012 by Cisco Systems, Inc. Compiled  |
|              |           |                  |                   |                |                         |                        |                2/17/2016 22:00:00               |
_________________________________________________________________________________________________________________________________________________________________________________________
salt.runners.net.multi_find(*patterns, **kwargs)

Execute multiple search tasks. This function is based on the find function. Depending on the search items, some information might overlap.

Optional arguments:

best: True
Return only the best match with the interfaces IP networks when the saerching pattern is a valid IP Address or Network.
display: True
Display on the screen or return structured object? Default: True (return on the CLI).

CLI Example:

$ sudo salt-run net.multi_find Ethernet1/49 xe-0/1/2

Output Example:

Pattern "Ethernet1/49" found in one of the following LLDP details

    -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
    |    Device    | Interface | Parent Interface | Remote Chassis ID | Remote Port Description | Remote Port ID |          Remote System Description          |   Remote System Name   |
    -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
    | edge01.oua04 |  xe-0/1/2 |       ae1        | DE:AD:BE:EF:DE:AD |       Ethernet1/49      |                | Cisco NX-OS(tm) n6000, Software (n6000-uk9) | edge07.oua04.dummy.net |
    -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

Details for interface xe-0/1/2

    -----------------------------------------------------------------------------------------------------------------------
    |    Device    | Interface | Interface Description | IP Addresses | Enabled |  UP  |    MAC Address    | Speed [Mbps] |
    -----------------------------------------------------------------------------------------------------------------------
    | edge01.oua04 |  xe-0/1/2 |     ae1 sw01.oua04    |              |   True  | True | BE:EF:DE:AD:BE:EF |    10000     |
    -----------------------------------------------------------------------------------------------------------------------

LLDP Neighbors for interface xe-0/1/2

    -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
    |    Device    | Interface | Parent Interface | Remote Chassis ID | Remote Port Description | Remote Port ID |          Remote System Description          |   Remote System Name   |
    -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
    | edge01.oua04 |  xe-0/1/2 |       ae1        | DE:AD:BE:EF:DE:AD |       Ethernet1/49      |                | Cisco NX-OS(tm) n6000, Software (n6000-uk9) | edge07.oua04.dummy.net |
    -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------