162 lines
5.5 KiB
Plaintext
162 lines
5.5 KiB
Plaintext
=head1 NAME
|
|
|
|
App::Netdisco::Manual::WritingCorePlugins - Documentation on Backend Driver
|
|
Plugins for Developers
|
|
|
|
=head1 Introduction
|
|
|
|
L<App::Netdisco>'s plugin system allows users to create backend I<drivers>
|
|
which use different I<transports> to gather information from network devices
|
|
and store in the database.
|
|
|
|
For example, transports might be SNMP, SSH, or HTTPS. Drivers might be
|
|
combining those transports with application protocols such as SNMP, NETCONF
|
|
(OpenConfig with XML), RESTCONF (OpenConfig with JSON), eAPI, or even CLI
|
|
scraping.
|
|
|
|
Drivers can be restricted to certain vendor platforms using familiar ACL
|
|
syntax. They are also attached to specific phases in Netdisco's backend
|
|
operation.
|
|
|
|
See L<App::Netdisco::Core::Plugin> for more information about core plugins.
|
|
|
|
=head1 Developing Plugins
|
|
|
|
A plugin is a Perl module which is loaded. Therefore it can do anything you
|
|
like, but the module will make a connection to a device, gather some data, and
|
|
store it in Netdisco's database.
|
|
|
|
App::Netdisco plugins must load the L<App::Netdisco::Core::Plugin> module.
|
|
This exports a set of helper subroutines to register the driver. Here's the
|
|
boilerplate code for our example plugin module:
|
|
|
|
package App::Netdisco::Core::Plugin::Discover::Wireless::UniFi;
|
|
|
|
use Dancer ':syntax';
|
|
use Dancer::Plugin::DBIC;
|
|
use App::Netdisco::Core::Plugin;
|
|
|
|
# driver registration code goes here, ** see below **
|
|
|
|
true;
|
|
|
|
=head1 Registering a Driver
|
|
|
|
Use the C<register_core_driver> helper from L<App::Netdisco::Core::Plugin> to
|
|
register a driver:
|
|
|
|
register_core_driver( \%driverconf, $coderef );
|
|
|
|
For example:
|
|
|
|
register_core_driver({
|
|
driver => 'unifiapi',
|
|
phase => 'discover_wireless',
|
|
}, sub { "driver code here" });
|
|
|
|
An explanation of the C<%driverconf> options is below. The C<$coderef> is the
|
|
main body of your driver. Your driver is run in a L<Try::Tiny> statement to
|
|
catch errors, and passed the following arguments:
|
|
|
|
$coderef->($device, $driverconf);
|
|
|
|
The C<$device> is an instance of L<App::Netdisco::DB::Result::Device>; that
|
|
is, a representation of a row in the database. Note that for early discover
|
|
phases this row may not yet exist in the database. The C<$driverconf> hashref
|
|
is the set of configuration parameters you used to declare the driver
|
|
(documented below).
|
|
|
|
=head2 Required Parameters
|
|
|
|
You must register drivers with a C<driver> and a C<phase> parameter.
|
|
|
|
The C<driver> is a label associated with a group of drivers and typically
|
|
refers to the combination of transport and application protocol. Examples
|
|
include C<snmp>, C<netconf>, C<restconf>, C<eapi>, and C<cli>. The convention
|
|
is for driver names to be lowercase. Users use the driver name to associate
|
|
authentication configuration settings with the correct drivers.
|
|
|
|
The C<phase> corresponds to the action run by Netdisco's backend, with the
|
|
addition of wrapping phases for additional windows of execution. The list of
|
|
so-called I<main> phases is below (and you can see the actions these map to):
|
|
|
|
core_phases:
|
|
- discover_properties
|
|
- discover_interfaces
|
|
- discover_vlans
|
|
- discover_wireless
|
|
- discover_entities
|
|
- macsuck_nodes
|
|
- arpnip_nodes
|
|
- arpnip_subnets
|
|
- netbios_stat
|
|
|
|
Each main phase also has C<before> and C<after> phases. For example the
|
|
C<arpnip_nodes> phase will have C<before_arpnip_nodes> and
|
|
C<after_arpnip_nodes> phases available when you register a driver. Note the
|
|
significance of the Return Code, and execution order, of drivers in these
|
|
phases, explained below.
|
|
|
|
=head2 Optional Parameters
|
|
|
|
Drivers may have C<only> and C<no> parameters configured which use the
|
|
standard ACL syntax described in
|
|
L<the settings guide|App::Netdisco::Manual::Configuration>. The C<only>
|
|
directive is especially useful as it can restrict a driver to a given device
|
|
platform or operating system (for example Cisco IOS XR, for RESTCONF).
|
|
|
|
=head2 Driver Execution and Return Code
|
|
|
|
Drivers are configured as an ordered list (in C<collector_plugins> or
|
|
C<extra_collector_plugins>). For the C<before> and C<after> phases of any
|
|
action, drivers are run in the order loaded. For the main phase of any action
|
|
they are run in REVERSE order. This has the effect that driver plugins loaded
|
|
through C<extra_collector_plugins> will be run I<before> core drivers.
|
|
|
|
The return code of the driver is ignored for C<before> and C<after> phases,
|
|
but is significant for the main phase of the action. During this phase if any
|
|
driver returns a true value then the main phase is deemed to have been
|
|
satisfied and Netdsico will move on to any C<after> driver plugins.
|
|
|
|
Remember that a driver is only run if it matches the hardware platform of the
|
|
target device and the user's configuration, and is not also excluded by the
|
|
user's configuration.
|
|
|
|
=head2 Accessing Transports
|
|
|
|
From your driver you will want to connect to a device to gather data. This is
|
|
done using a transport protocol session (SNMP, SSH, etc). Transports are
|
|
singleton objects instantiated on demand, so they can be shared among a series
|
|
of action phases that are accessing the same device.
|
|
|
|
See the documentation for each transport to find out how to access it:
|
|
|
|
=over 4
|
|
|
|
=item *
|
|
|
|
L<App::Netdisco::Core::Transport::SNMP>
|
|
|
|
=item *
|
|
|
|
L<App::Netdisco::Core::Transport::HTTPS>
|
|
|
|
=item *
|
|
|
|
L<App::Netdisco::Core::Transport::SSH>
|
|
|
|
=back
|
|
|
|
=head2 Database Connections
|
|
|
|
The Netdisco database is available via the C<netdisco> schema key, as below.
|
|
You can also use the C<external_databases> configuration item to set up
|
|
connections to other databases.
|
|
|
|
# plugin code
|
|
use Dancer::Plugin::DBIC;
|
|
schema('netdisco')->resultset('Devices')->search({vendor => 'cisco'});
|
|
|
|
=cut
|
|
|