/ 
App-Netdisco-2.088003
River stage one • 1 direct dependent • 1 total dependent
⭐ Starred 676 GitHub stars
/ netdisco-do

NAME

netdisco-do - Run any Netdisco job from the command-line.

SYNOPSIS

~/bin/netdisco-do <action> [-DISQR] [--enqueue] [--force] [--quiet] [-d <device> [-p <port>] [-e <extra>]]

DESCRIPTION

This program allows you to run any Netdisco poller job from the command-line.

ACTIONS

Note that some jobs (discoverall, macwalk, arpwalk, nbtwalk) simply add entries to the Netdisco job queue for other jobs, so won't seem to do much when you trigger them. Everything else happens in real-time.

However the "--enqueue" option will force the queueing of the job, regardless of type. This may be useful for cron-driven actions, or for actions working across large IP spaces. Netdisco will refuse to queue more than 512 jobs at once unless you also add the "--force" option.

For any action, if you wish to run one of its individual worker stages, then pass action::stage as the first argument to netdisco-do, for example discover::neighbors.

Any action taking a device parameter can be passed either a hostname or IP address of any interface of a known or unknown device, or an IP prefix (subnet) which will cause netdisco-do to run the action on all addresses in that range. The device parameter may also be a filename that Netdisco will open to read hostnames, IPs, or prefixes, one per line.

The device parameter may be passed multiple times. In this case, all addresses (after expanding IP Prefixes) will be handled one by one.

discover

Run a discover on the device (specified with -d).

~/bin/netdisco-do discover -d 192.0.2.1

Run a discover on two different devices (specified with -d).

~/bin/netdisco-do discover -d 192.0.2.1 -d 192.15.2.95

discoverall

Queue a discover for all known devices.

pingsweep

Scan an IP prefix (subnet) using ping utility (must be installed), any host responding has a discover job queued. It is recommended to queue the pingsweep job as well.

~/bin/netdisco-do pingsweep -d 192.0.2.0/24 --enqueue

The default ping timeout is 0.1 seconds. To change this, pass any number to the -e parameter.

macsuck

Run a macsuck on the device (specified with -d).

~/bin/netdisco-do macsuck -d 192.0.2.1

Submit macsuck data directly to Netdisco in JSON format (see API web docs for data format example):

# pipe to standard input
~/bin/netdisco-do macsuck -d 192.0.2.1 -e '@-'
# read from a file
~/bin/netdisco-do macsuck -d 192.0.2.1 -e '@/tmp/mac-address-table.json'
# pass directly
~/bin/netdisco-do macsuck -d 192.0.2.1 -e '[{"ip": "string", "mac": "string", "dns": "string"}]'

macwalk

Queue a macsuck for all known devices.

arpnip

Run an arpnip on the device (specified with -d).

~/bin/netdisco-do arpnip -d 192.0.2.1

Submit arpnip data directly to Netdisco in JSON format (see API web docs for data format example):

# pipe to standard input
~/bin/netdisco-do arpnip -d 192.0.2.1 -e '@-'
# read from a file
~/bin/netdisco-do arpnip -d 192.0.2.1 -e '@/tmp/mac-address-table.json'
# pass directly
~/bin/netdisco-do arpnip -d 192.0.2.1 -e '[{"ip": "string", "mac": "string", "dns": "string"}]'

arpwalk

Queue an arpnip for all known devices.

delete

Delete a device (specified with -d). Pass a log message for the action in the -e parameter. Optionally request for associated nodes to be archived (rather than deleted) by setting the -p parameter to "yes" (mnemonic: preserve).

~/bin/netdisco-do delete -d 192.0.2.1
~/bin/netdisco-do delete -d 192.0.2.1 -e 'older than the sun'
~/bin/netdisco-do delete -d 192.0.2.1 -e 'older than the sun' -p yes

renumber

Change the canonical IP address of a device (specified with -d). Pass the new IP address in the -e parameter. All related records such as topology, log and node information will also be updated to refer to the new device.

Note that no check is made as to whether the new IP is reachable for future polling.

~/bin/netdisco-do renumber -d 192.0.2.1 -e 192.0.2.254

nbtstat

Run an nbtstat on the node (specified with -d).

~/bin/netdisco-do nbtstat -d 192.0.2.2

nbtwalk

Queue an nbtstat for all known nodes.

Custom Field update

Update a Device or Device Port custom field using `netdisco-do`. Specify the field name as the "action" prefixed with `cf_`. The content can be passed in the command, or taken from a file, or from standard input.

# pass directly
~/bin/netdisco-do cf_myfield --enqueue -d 192.0.2.1 -e 'field value'
# pipe from standard input
~/bin/netdisco-do cf_myfield --enqueue -d 192.0.2.1 -e '@-'
# read from a file
~/bin/netdisco-do cf_myfield --enqueue -d 192.0.2.1 -e '@/tmp/myfield'

Note that `--enqueue ` is *required* for the feature to work. The change is, however, applied instanty in the database when `netdisco-do` runs.

expire

Run Device and Node expiry actions according to configuration.

expirenodes

Archive nodes on the specified device. If you want to delete nodes, set the -e parameter to "no" (mnemonic: expire). If you want to perform the action on a specific port, set the -p parameter.

~/bin/netdisco-do expirenodes -d 192.0.2.1
~/bin/netdisco-do expirenodes -d 192.0.2.1 -p FastEthernet0/1 -e no

graph

Generate GraphViz graphs for the largest cluster of devices.

You'll need to install the Graph::Undirected and GraphViz Perl modules, and possibly also the graphviz utility for your operating system. Also create a directory for the output files.

mkdir ~/graph
~/bin/localenv cpanm Graph::Undirected
~/bin/localenv cpanm GraphViz

show

Dump the content of an SNMP MIB Object or an SNMP::Info method, useful for diagnostics and troubleshooting.

You should provide the "-e" option which is the name of the method or object, such as interfaces or uptime or ifDescr.

If you wish to specify the SNMP MIB to load and find the Object in, then you can qualify the "-e" parameter, such as IF-MIB::ifDescr.

If you wish to test with a specific SNMP::Info device class other than the one discovered, pass this in the "-p" parameter, such as Layer3 or SNMP::Info::Layer3 (the SNMP::Info prefix is optional).

All "-e" parameters are case sensitive.

~/bin/netdisco-do show -d 192.0.2.1 -e interfaces
~/bin/netdisco-do show -d 192.0.2.1 -e IF-MIB::ifDescr
~/bin/netdisco-do show -d 192.0.2.1 -e interfaces -p SNMP::Info::Layer2::HP
~/bin/netdisco-do show -d 192.0.2.1 -e ifName -p Layer3::Arista

The "-e" parameter specify will show the used configuration for the specified device.

~/bin/netdisco-do show -d 192.0.2.1 -e specify

Passing the " --quiet " command line flag will cause show to return data in a compact JSON format (suitable for piping to jq, for example).

If the output is very long, you may see a "skipping..." message. Work around this by passing " --quiet " and then pipe the output to "jq .".

This command works well with the "-I" debug flag on SNMP::Info (or "-II").

psql

Start an interactive terminal with the Netdisco PostgreSQL database. If you pass an SQL statement in the -e option then it will be executed.

~/bin/netdisco-do psql
~/bin/netdisco-do psql -e 'SELECT ip, dns FROM device'
~/bin/netdisco-do psql -e 'COPY (SELECT ip, dns FROM device) TO STDOUT WITH CSV HEADER'

stats

Updates Netdisco's statistics on number of devices, nodes, etc, for today.

location

Set the SNMP location field on the device (specified with -d). Pass the location string in the -e extra parameter. Use --force to bypass user access controls.

~/bin/netdisco-do location -d 192.0.2.1 -e 'wiring closet'

contact

Set the SNMP contact field on the device (specified with -d). Pass the contact name in the -e extra parameter. Use --force to bypass user access controls.

~/bin/netdisco-do contact -d 192.0.2.1 -e 'tel: 555-2453'

portname

Set the description on a device port. Requires the -d parameter (device), -p parameter (port), and -e parameter (description). Use --force to bypass user access controls.

~/bin/netdisco-do portname -d 192.0.2.1 -p FastEthernet0/1 -e 'Web Server'

portcontrol

Set the up/down status on a device port. Requires the -d parameter (device), -p parameter (port), and -e parameter ("up" or "down"). Use --force to bypass user access controls.

~/bin/netdisco-do portcontrol -d 192.0.2.1 -p FastEthernet0/1 -e up
~/bin/netdisco-do portcontrol -d 192.0.2.1 -p FastEthernet0/1 -e down

vlan

Set the native VLAN on a device port. Requires the -d parameter (device), -p parameter (port), and -e parameter (VLAN number). Use --force to bypass user access controls.

~/bin/netdisco-do vlan -d 192.0.2.1 -p FastEthernet0/1 -e 102

power

Set the PoE on/off status on a device port. Requires the -d parameter (device), -p parameter (port), and -e parameter ("on" or "off"). Use --force to bypass user access controls.

~/bin/netdisco-do power -d 192.0.2.1 -p FastEthernet0/1 -e on
~/bin/netdisco-do power -d 192.0.2.1 -p FastEthernet0/1 -e off

makerancidconf

Generates rancid configuration for known devices. See App::Netdisco::Worker::Plugin::MakeRancidConf for configuration needs.

~/bin/netdisco-do makerancidconf

getapikey

Generates an API key for the supplied username. See the API doc for further information.

~/bin/netdisco-do getapikey -e the_username

dumpconfig

Will dump the loaded and parsed configuration for the application. Pass a specific configuration setting name to the -e parameter to dump only that.

Some configuration items like device_auth are evaluated against the ACL first. Pass a device in -d to display them:

~/bin/netdisco-do dumpconfig -d 192.0.2.1 -e device_auth

loadmibs

A requirement for web browsing of SNMP data (see snapshot command), run this to load Netdisco MIBs into the database. It only needs to be done once.

snapshot

Builds and saves a data structure which Netdisco can use to mimic the device (if shared) and also browse the SNMP Objects in the web.

By default the command will gather Objects which can be downloaded from the web under Device Details tab. This allows another user to mimic your device.

If you previously ran the loadmibs action before running this action, the Objects also become browsable in the web (under Device SNMP tab).

Normally the SNMP Objects are all gathered from .1 root but you can use -e parameter to change this.

addpseudodevice

Adds a Pseudo Device which can be used to connect together unconnected parts of your network or to gather ARP via CLI/API when SNMP is not available.

Pass the Pseudo Device IP in the -d parameter. Pass the Pseudo Device name in the -e parameter. Pass the number of ports (one or more) in the -p parameter. All parameters are required. For example:

~/bin/netdisco-do addpseudodevice -d 192.0.2.1 -e fakerouter -p 10

DEBUG OPTIONS

The flag "-R" will cause any changes to the database to be rolled back at the end of the action.

The flags "-DISQ" can be specified, multiple times, and enable the following items in order:

-D

Netdisco debug log level.

-I or -II

SNMP::Info trace level (1 or 2).

-S or -SS or -SSS

SNMP (net-snmp) trace level (1, 2 or 3).

-Q

DBIx::Class trace enabled.

In case of issues with the colored output, setting the environment variable ANSI_COLORS_DISABLED or NO_COLOR can be used to suppress it.

The --dry-run option can be provided to show the workers that will run without actually executing their content. Setting the ND2_WORKER_ROLL_CALL environment variable does the same thing.