# salt.pillar.netbox

A module that adds data to the Pillar structure from a NetBox API.

New in version 2019.2.0.

## Configuring the NetBox ext_pillar

To use this pillar, you must first create a token in your NetBox instance at http://netbox.example.com/user/api-tokens/ (substituting the hostname of your NetBox instance)

The NetBox api_url and api_token must be set in the master config.

For example `/etc/salt/master.d/netbox.conf`:

    ext_pillar:
      - netbox:
          api_url: http://netbox.example.com/api/
          api_token: 123abc

The following options are optional, and determine whether or not the module will attempt to configure the `proxy` pillar data for use with the napalm proxy-minion:

    proxy_return: True
    proxy_username: admin

By default, this module will query the NetBox API for the platform associated with the device, and use the 'NAPALM driver' field to set the napalm proxy-minion driver. (Currently only 'napalm' is supported for drivertype.)

This module currently only supports the napalm proxy minion and assumes you will use SSH keys to authenticate to the network device. If password authentication is desired, it is recommended to create another `proxy` key in pillar_roots (or git_pillar) with just the `passwd` key and use `salt.renderers.gpg` to encrypt the value.

If you use more than one username for your devices, leave proxy_username unset, and set the `username` key in your pillar as well. If any additional options for the proxy setup are needed, they should also be configured in pillar_roots.

Other available configuration options:

site_details: `True`

  Whether should retrieve details of the site the device belongs to.

site_prefixes: `True`

  Whether should retrieve the prefixes of the site the device belongs to.

devices: `True`

  New in version 3004.0.

  Whether should retrieve physical devices.

virtual_machines: `False`

  New in version 3004.0.

  Whether should retrieve virtual machines.

interfaces: `False`

  New in version 3004.0.

  Whether should retrieve the interfaces of the device.

interface_ips: `False`

  New in version 3004.0.

  Whether should retrieve the IP addresses for interfaces of the device. (interfaces must be set to True as well)

api_query_result_limit: `Use NetBox default`

  New in version 3004.0.

  An integer specifying how many results should be returned for each query to the NetBox API. Leaving this unset will use NetBox's default value.

Note that each option you enable can have a detrimental impact on pillar performance, so use them with caution.

After configuring the pillar, you must restart the Salt master for the changes to take effect.

For example:

    systemctl restart salt-master

To query perform a quick test of the pillar, you should refresh the pillar on the minion with the following:

    salt minion1 saltutil.refresh_pillar

And then query the pillar:

    salt minion1 pillar.items 'netbox'

Example output:

    minion1:
        netbox:
            ----------
            id:
                511
            url:
                https://netbox.example.com/api/dcim/devices/511/
            name:
                minion1
            node_type:
                device
            display_name:
                minion1
            device_type:
                ----------
                id:
                    4
                url:
                    https://netbox.example.com/api/dcim/device-types/4/
                manufacturer:
                    ----------
                    id:
                        1
                    url:
                        https://netbox.example.com/api/dcim/manufacturers/1/
                    name:
                        Cisco
                    slug:
                        cisco
                model:
                    ISR2901
                slug:
                    isr2901
                display_name:
                    Cisco ISR2901
            device_role:
                ----------
                id:
                    45
                url:
                    https://netbox.example.com/api/dcim/device-roles/45/
                name:
                    Network
                slug:
                    network
            interfaces:
                |_
                  ----------
                  id:
                      8158
                  ip_addresses:
                      |_
                        ----------
                        id:
                            1146
                        url:
                            https://netbox.example.com/api/ipam/ip-addresses/1146/
                        family:
                            ----------
                            value:
                                4
                            label:
                                IPv4
                        address:
                            192.0.2.1/24
                        vrf:
                            None
                        tenant:
                            None
                        status:
                            ----------
                            value:
                                active
                             label:
                                Active
                        role:
                            None
                        nat_inside:
                            None
                        nat_outside:
                            None
                        dns_name:
                        description:
                        tags:
                        custom_fields:
                        created:
                            2021-02-19
                        last_updated:
                            2021-02-19T06:12:04.153386Z
                  url:
                      https://netbox.example.com/api/dcim/interfaces/8158/
                  name:
                      GigabitEthernet0/0
                  label:
                  type:
                      ----------
                      value:
                          1000base-t
                      label:
                          1000BASE-T (1GE)
                  enabled:
                      True
                  lag:
                      None
                  mtu:
                      None
                  mac_address:
                      None
                  mgmt_only:
                      False
                  description:
                  mode:
                      None
                  untagged_vlan:
                      None
                  tagged_vlans:
                  cable:
                      None
                  cable_peer:
                      None
                  cable_peer_type:
                      None
                  connected_endpoint:
                      None
                  connected_endpoint_type:
                      None
                  connected_endpoint_reachable:
                      None
                  tags:
                  count_ipaddresses:
                      1
                |_
                  ----------
                  id:
                      8159
                  ip_addresses:
                      |_
                        ----------
                        id:
                            1147
                        url:
                            https://netbox.example.com/api/ipam/ip-addresses/1147/
                        family:
                            ----------
                            value:
                                4
                            label:
                                IPv4
                        address:
                            198.51.100.1/24
                        vrf:
                            None
                        tenant:
                            None
                        status:
                            ----------
                            value:
                                active
                            label:
                                Active
                        role:
                            None
                        nat_inside:
                            None
                        nat_outside:
                            None
                        dns_name:
                        description:
                        tags:
                        custom_fields:
                        created:
                            2021-02-19
                        last_updated:
                            2021-02-19T06:12:40.508154Z
                        url:
                            https://netbox.example.com/api/dcim/interfaces/8159/
                        name:
                            GigabitEthernet0/1
                        label:
                        type:
                            ----------
                            value:
                                1000base-t
                            label:
                                1000BASE-T (1GE)
                        enabled:
                            True
                        lag:
                            None
                        mtu:
                            None
                        mac_address:
                            None
                        mgmt_only:
                            False
                        description:
                        mode:
                            None
                        untagged_vlan:
                            None
                        tagged_vlans:
                        cable:
                            None
                        cable_peer:
                            None
                        cable_peer_type:
                            None
                        connected_endpoint:
                            None
                        connected_endpoint_type:
                            None
                        connected_endpoint_reachable:
                            None
                        tags:
                        count_ipaddresses:
                            1
            tenant:
                None
            platform:
                ----------
                id:
                    1
                url:
                    https://netbox.example.com/api/dcim/platforms/1/
                name:
                    Cisco IOS
                slug:
                    ios
            serial:
            asset_tag:
                None
            site:
                ----------
                id:
                    18
                url:
                    https://netbox.example.com/api/dcim/sites/18/
                name:
                    Site 1
                slug:
                    site1
                status:
                    ----------
                    value:
                        active
                    label:
                        Active
                region:
                    None
                tenant:
                    None
                facility:
                asn:
                    None
                time_zone:
                    None
                description:
                physical_address:
                shipping_address:
                latitude:
                    None
                longitude:
                    None
                contact_name:
                contact_phone:
                contact_email:
                comments:
                tags:
                custom_fields:
                created:
                    2021-02-25
                last_updated:
                    2021-02-25T14:21:07.898957Z
                circuit_count:
                    0
                device_count:
                    1
                prefix_count:
                    2
                rack_count:
                    0
                virtualmachine_count:
                    1
                vlan_count:
                    0
                prefixes:
                    |_
                      ----------
                      id:
                          284
                      url:
                          https://netbox.example.com/api/ipam/prefixes/284/
                      family:
                          ----------
                          value:
                              4
                          label:
                              IPv4
                      prefix:
                          192.0.2.0/24
                      vrf:
                          None
                      tenant:
                          None
                      vlan:
                          None
                            ----------
                          value:
                              active
                          label:
                              Active
                      role:
                          None
                      is_pool:
                          False
                      description:
                      tags:
                      custom_fields:
                      created:
                          2021-02-25
                      last_updated:
                          2021-02-25T15:08:27.136305Z
                    |_
                      ----------
                      id:
                          285
                      url:
                          https://netbox.example.com/api/ipam/prefixes/285/
                      family:
                          ----------
                          value:
                              4
                          label:
                              IPv4
                      prefix:
                          198.51.100.0/24
                      vrf:
                          None
                      tenant:
                          None
                      vlan:
                          None
                      status:
                          ----------
                          value:
                              active
                          label:
                              Active
                      role:
                          None
                      is_pool:
                          False
                      description:
                      tags:
                      custom_fields:
                      created:
                          2021-02-25
                      last_updated:
                          2021-02-25T15:08:59.880440Z
            rack:
                None
            position:
                None
            face:
                None
            parent_device:
                None
            status:
                ----------
                value:
                    active
                label:
                    Active
            primary_ip:
                ----------
                id:
                    1146
                url:
                    https://netbox.example.com/api/ipam/ip-addresses/1146/
                family:
                    4
                address:
                    192.0.2.1/24
            primary_ip4:
                ----------
                id:
                    1146
                url:
                    https://netbox.example.com/api/ipam/ip-addresses/1146/
                family:
                    4
                address:
                    192.0.2.1/24
            primary_ip6:
                None
            cluster:
                None
            virtual_chassis:
                None
            vc_position:
                None
            vc_priority:
                None
            comments:
            local_context_data:
                None
            tags:
            custom_fields:
            config_context:
            created:
                2021-02-19
            last_updated:
                2021-02-19T06:12:04.171105Z

salt.pillar.netbox.ext_pillar(minion_id, pillar, *args, **kwargs)

  Query NetBox API for minion data