# salt.runners.net

## NET Finder

Added 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 |
          -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------