add documentation for device_identity

lib/App/Netdisco/Manual/Configuration.pod

@@ -89,7 +89,8 @@ device DNS name (using a fresh DNS lookup, so works on new discovery), e.g.:
 =item *
 
 "C<property:regexp>" - matched against a device property, such as C<model> or
-C<vendor> (with enforced begin/end regexp anchors).
+C<vendor> (with enforced begin/end regexp anchors). When matching a device's
+interface (see C<device_identity>), "C<port:regexp>" is also an option.
 
  - vendor:cisco
 
@@ -604,6 +605,62 @@ As you can see, a host group is referenced by prefixing its name with
 YAML syntax too). Host groups may be used in any setting that mentions support
 for L</"ACCESS CONTROL LISTS">.
 
+=head3 C<device_identity>
+
+Value: Dictionary of Access Control Lists. Default: None.
+
+This setting allows you to control the canonical name or identity of devices
+in Netdisco. For example if Netdisco discovers devices and uses the "wrong"
+interface to identfy them (thereby confusing users) you can correct that here.
+
+The C<device_identity> setting is a dictionary where the key should match a
+device as Netdisco knows it, and the value should match one of the device's
+interfaces to use as its new canonical identity. Both keys and values are
+Access Control Lists as described in L</"ACCESS CONTROL LISTS"> (but with
+additional features, see below).
+
+In general, because the key of a dictionary must be a simple text string, you
+can use hostname, IP prefix, device properties, and group references to match
+devices. Regular expressions and combinations of device attributes should be
+placed in a C<host_groups> entry and referenced by name. For example:
+
+ host_groups:
+   backbone_devices:
+     - 'op:and'
+     - 'vendor:arista'
+     - 'model:.*(?i:DCS7508).*'
+ 
+ device_identity:
+   'group:backbone_devices':
+     - !!perl/regexp ^.*\.backbone\.example\.com$
+     - '172.16.20.0/24'
+   'vendor:cisco': '192.0.2.0/24'
+
+During "discover" jobs, Netdisco will find all entries in C<device_identity>
+where the I<key> matches the device. For those entries, the device's interface
+IPs are put in ascending order, and then tested against the C<device_identity>
+I<value> in turn. If any interface matches, then the device is renumbered to
+use that interface as its new identity and the process stops.
+
+When using an Access Control List for the value (interface selection), as well
+as the options described in L</"ACCESS CONTROL LISTS"> you can use
+"C<port:regexp>" to match an interface's port name. For example to renumber
+all Arista devices to the IP and host name of their Vlan1 interface (if they
+have one), you could use:
+
+ device_identity:
+   'vendor:arista': 'port:(?i)vlan1'
+
+Once a device is renumbered, its new identity is "sticky". That is, you could
+remove the C<device_identity> configuration and the next "discover" job will
+not revert any device's identity.
+
+Remember that all L</"ACCESS CONTROL LISTS"> have an implicit "OR" condition -
+any of their entries matching will cause the whole list to match.  If you need
+very specific matching on devices, use a host group of several properties
+together with the "C<op:and>" modifier to require that all items in the list
+match the device (as in the example above).
+
 =head3 C<mibhome>
 
 Value: Directory. Default: C<${HOME}/netdisco-mibs>.