rename all the things
This commit is contained in:
Oliver Gorwits
@@ -1,161 +0,0 @@
|
||||
=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
|
||||
|
||||
181
lib/App/Netdisco/Manual/WritingCoreWorkers.pod
Normal file
181
lib/App/Netdisco/Manual/WritingCoreWorkers.pod
Normal file
@@ -0,0 +1,181 @@
|
||||
=head1 NAME
|
||||
|
||||
App::Netdisco::Manual::WritingCoreWorkers - Developer Documentation on Core Plugins
|
||||
|
||||
=head1 Introduction
|
||||
|
||||
L<App::Netdisco>'s plugin system allows users to write I<workers> to gather
|
||||
information from network devices using different I<transports> and store
|
||||
results in the database.
|
||||
|
||||
For example, transports might be SNMP, SSH, or HTTPS. Workers might be
|
||||
combining those transports with application protocols such as SNMP, NETCONF
|
||||
(OpenConfig with XML), RESTCONF (OpenConfig with JSON), eAPI, or even CLI
|
||||
scraping. The combination of transport and protocol is known as a I<driver>.
|
||||
|
||||
Workers can be restricted to certain vendor platforms using familiar ACL
|
||||
syntax. They are also attached to specific actions in Netdisco's backend
|
||||
operation (discover, macsuck, etc).
|
||||
|
||||
See L<App::Netdisco::Core::Plugin> for more information about core plugins.
|
||||
|
||||
=head1 Developing Workers
|
||||
|
||||
A worker is Perl code which is run. Therefore it can do anything you like, but
|
||||
typically it 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 helper subroutine to register the worker. Here's the
|
||||
boilerplate code for our example plugin module:
|
||||
|
||||
package App::Netdisco::Core::Plugin::Discover::Wireless::UniFi;
|
||||
|
||||
use Dancer ':syntax';
|
||||
use App::Netdisco::Core::Plugin;
|
||||
|
||||
# worker registration code goes here, ** see below **
|
||||
|
||||
true;
|
||||
|
||||
=head1 Registering a Worker
|
||||
|
||||
Use the C<register_core_worker> helper from L<App::Netdisco::Core::Plugin> to
|
||||
register a worker:
|
||||
|
||||
register_core_worker( \%workerconf, $coderef );
|
||||
|
||||
For example:
|
||||
|
||||
register_core_worker({
|
||||
driver => 'unifiapi',
|
||||
}, sub { "worker code here" });
|
||||
|
||||
An explanation of the C<%workerconf> options is below. The C<$coderef> is the
|
||||
main body of your worker. Your worker is run in a L<Try::Tiny> statement to
|
||||
catch errors, and passed the following arguments:
|
||||
|
||||
$coderef->($device, $workerconf);
|
||||
|
||||
The C<$device> is an instance of L<App::Netdisco::DB::Result::Device> (that
|
||||
is, an object representation of a row in the database). Note that for early
|
||||
discover phases this row may not yet exist in the database. The C<$workerconf>
|
||||
hashref is the set of configuration parameters you used to declare the worker
|
||||
(documented below).
|
||||
|
||||
=head2 Package Naming Convention
|
||||
|
||||
The package name used where the worker is declared is significant. Let's look
|
||||
at the boilerplate example again:
|
||||
|
||||
package App::Netdisco::Core::Plugin::Discover::Wireless::UniFi;
|
||||
|
||||
Workers registered in this package will be run during the I<discover> backend
|
||||
action (that is, during a C<discover> job). You can replace C<Discover> with
|
||||
other actions such as C<Macsuck>, C<Arpnip>, C<Expire>, and C<Nbtstat>.
|
||||
|
||||
The component after the action is known as the I<phase> (C<Wireless> in this
|
||||
example), and is the way to override a Netdisco built-in worker, by using the
|
||||
same name (plus an entry in C<$workerconf>, see below). Otherwise you can use
|
||||
any valid Perl bareword for the phase.
|
||||
|
||||
=head2 Required Parameters
|
||||
|
||||
You must register workers with a C<driver> parameter.
|
||||
|
||||
The C<driver> is a label associated with a group of workers 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. Use the driver name to associate
|
||||
authentication configuration settings with the correct workers.
|
||||
|
||||
=head2 Optional Parameters
|
||||
|
||||
Workers 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 worker to a given device platform or
|
||||
operating system (for example Cisco IOS XR for the C<restconf> driver).
|
||||
|
||||
The C<hook> parameter tells Netdisco the role that your worker plays in the
|
||||
backend action. It can have one of three values:
|
||||
|
||||
=over 4
|
||||
|
||||
=item before
|
||||
|
||||
A worker that is essential to the action and run before any other workers
|
||||
within the same action. For example at the start of C<discover> we need to
|
||||
gather basic parameters and create a C<device> row in the database. The first
|
||||
C<before> worker which succeeds will short-circuit any others (see Return
|
||||
Code, below).
|
||||
|
||||
=item on
|
||||
|
||||
This worker is run alongside others with the same phase, and also
|
||||
short-curcuits any other workers in the same phase (see Return Code, below).
|
||||
|
||||
=item after
|
||||
|
||||
This worker is run alongside others with the same phase. All workers are run,
|
||||
regardless of their return code.
|
||||
|
||||
=back
|
||||
|
||||
=head2 Worker Execution and Return Code
|
||||
|
||||
Workers are configured as an ordered list. They are grouped by C<action> and
|
||||
C<phase> (as in Package Naming Convention, above).
|
||||
|
||||
Workers defined in C<extra_core_plugins> are run before those in
|
||||
C<core_plugins> so you have an opportunity to override core workers by
|
||||
adding them to C<extra_core_plugins> and setting C<hook> to C<on> in the
|
||||
worker configuration.
|
||||
|
||||
The return code of the worker is ignored for those configured with hook
|
||||
C<after>, but is significant for those configured with C<befoe> or C<on>.
|
||||
If any worker returns a true value then the group at that phase is
|
||||
deemed to have been satisfied and Netdsico will move on to other worker
|
||||
plugins.
|
||||
|
||||
Remember that a worker 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 worker 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 set of
|
||||
workers 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 package
|
||||
use Dancer::Plugin::DBIC;
|
||||
schema('netdisco')->resultset('Devices')->search({vendor => 'cisco'});
|
||||
|
||||
=cut
|
||||
|
||||
Reference in New Issue
Block a user