Update Palo Alto Arp documentation

NOTES.rst

@@ -8,6 +8,27 @@ existing bug reports, go to https://github.com/uninett/nav/issues .
 To see an overview of upcoming release milestones and the issues they resolve,
 please go to https://github.com/uninett/nav/milestones .
 
+NAV 5.12
+========
+Deprecation warnings
+--------------------
+.. warning:: Configuration of Palo Alto firewall ARP cache access, which was
+               previously done using :file:`ipdevpoll.conf` in NAV 5.10 and NAV
+               5.11, must from NAV 5.12 onwards be done using a HTTP REST
+               API management profile. :ref:`See below
+               <5.12-new-http-rest-api-management-profile-type>`.
+
+.. _5.12-new-http-rest-api-management-profile-type:
+New way to configure fetching Palo Alto firewall ARP cache data
+---------------------------------------------------------------
+
+A new HTTP REST API management profile type has been added to NAV for
+configuring management of certain devices. Currently, this management profile
+type is only used to configure access to the ARP cache of Palo Alto
+ firewalls. For more details, head to the HTTP REST API section of the
+:ref:`management profile reference documentation<http-rest-api-management-profile>`.
+
+
 NAV 5.11
 ========
 

doc/reference/ipdevpoll.rst

@@ -106,35 +106,6 @@ Section [linkstate]
   The value ``any`` will generate alerts for all link state changes, but
   **this is not recommended** for performance reasons.
 
-Section [paloaltoarp]
----------------------
-
-This section configures the Palo Alto ARP plugin.  Palo Alto firewalls do
-support SNMP.  They do not, however, support fetching ARP cache data using
-SNMP.  This plugin enables fetching ARP records from Palo Alto firewalls using
-their built-in REST API.
-
-Currently, there is no management profile type for this type of REST APIs, so
-credentials to access a Palo Alto firewall's API must be configured in this
-section.
-
-If you have a Palo Alto firewall named ``example-fw.example.org``, with an IP
-address of ``10.0.42.42`` and a secret API token of
-``762e87e0ec051a1c5211a08dd48e7a93720eee63``, you can configure this in this
-section by adding::
-
-  example-fw.example.org = 762e87e0ec051a1c5211a08dd48e7a93720eee63
-
-Or, alternatively::
-
-  10.0.42.42 = 762e87e0ec051a1c5211a08dd48e7a93720eee63
-
-
-.. warning:: The Palo Alto ARP plugin does not currently verify TLS
-             certificates when accessing a Palo Alto API.  This will be changed
-             at a later date, but if it worries you, you should not use the
-             plugin yet.
-
 
 Job sections
 ------------

doc/reference/management-profiles.rst

@@ -90,3 +90,37 @@ Alternate port
 
 .. _`NAPALM`: https://napalm.readthedocs.io/en/latest/
 .. _`NETCONF`: https://en.wikipedia.org/wiki/NETCONF
+
+.. _http-rest-api-management-profile:
+HTTP REST APIs
+--------------
+Some devices are (to some extent) managed using a HTTP REST API. As an
+example, Palo Alto firewalls support SNMP, but ARP information must
+specifically be fetched using a HTTP REST API. As of NAV 5.12, HTTP
+REST API profiles are used to configure access to services of the following
+devices.
+
+`Palo Alto PAN-OS firewalls`_
+  A HTTP REST API profile is needed for NAV to access the firewall's ARP information.
+
+.. warning:: The Palo Alto ARP implementation in NAV does not currently verify TLS
+             certificates when accessing a Palo Alto API.  This will be changed
+             at a later date, but if it worries you, you should not configure
+             any netboxes to use the Palo Alto Arp service yet.
+
+.. image:: http-rest-api-profile-example.png
+
+If you have a Palo Alto firewall running on a netbox managed by NAV,
+with a secret API key of ``762e87e0ec051a1c5211a08dd48e7a93720eee63``,
+you can configure NAV to fetch ARP tables from this firewall by
+creating a new management profile with
+
+* protocol set to ``HTTP REST API``,
+
+* API key set to ``762e87e0ec051a1c5211a08dd48e7a93720eee63``,
+
+* service set to ``Palo Alto ARP``,
+
+and then add this management profile to the netbox.
+
+.. _`Palo Alto PAN-OS firewalls`: https://docs.paloaltonetworks.com/pan-os/11-0/pan-os-panorama-api/pan-os-xml-api-request-types/configuration-api/get-active-configuration/use-xpath-to-get-arp-information