1NETDISCO(1) User Contributed Perl Documentation NETDISCO(1)
2
6 netdisco - Internal API
7
9 This is the inside guts of the Netdisco executable. You should be
10 looking in README for how to use Netdisco.
11
13 Network Discovery
14 discover(host)
16 Discovers one device, stores its info, interfaces, and neighbors,
17 and returns.
18 refresh_all()
20 Calls discover() for each file already in device table.
21 run()
23 Event loop that calls discover() as long as the @Discover_Queue has
24 something in it.
25 schlop(file,topo_only_flag)
27 Used to start a discovery based on topography file. Will then
28 proceed to do an initial mac_suck() and arp_nip() unless the
29 topo_only_flag is set.
30 queue_process(device, action, [status])
32 Queue a request for this controller to perform an action.
33 topo_add_link([{},{}])
35 Pass reference to array of hash references holding link: lines from
36 manual topology info. Adds information to device_port table.
37 topo_load_file(filename)
39 Loads and parses manual topography file.
40 Utility Functions
42 add_user()
44 Takes 4 optional arguments from @ARGV = (user,pw,port,admin)
45 If all 4 are not there, then interactive mode is entered and
47 prompts are given.
48 batch_mode(name,time_too?)
50 Redirects STDOUT to a log file with timestamp.
51 Can be called recursively. call batch_mode_end() to return to
53 previous Output.
54 batch_mode_end(no_compress_flag)
56 Returns control of stdout to previous value, optionally compresses
57 the finished output file.
58 Function returns file name of closed output file.
60 Pass something as first parameter to force no compression.
62 end_int_handler
64 end()
65 Cleanup routine that is called upon interrupt (ctrl-c) or end of
66 routines.
67 Prints various statistics to stdout or batch_redirect() and calls
69 Netdisco::log().
70 load_old_devices()
72 Populates %Old_Devices with which devices are in the database.
73 load_old_nodes(days)
75 Populates %Old_Nodes with which nodes are in the database.
76 Nodes will have to have been seen in the last DAYS days.
78 parse_oui()
80 Parses file oui.txt in current directory. Uses contents to stuff
81 table "oui".
82 timeout()
84 Signal handler for SIGALARM
85 ok_to(dev,name,what)
87 Given a device or IP address, a display name (hostname or IP
88 address), and an action (arpnip, macsuck, discover), check the
89 configuration file for _no and _only configurations. Return 1 if
90 it's OK, or 0 if it's not OK.
91 SNMP Functions
93 arpnip()
95 Connects to device and reads its ARP cache. Then adds entries to
96 "node_ip" table.
97 Cheers to Jim Warner for the original arpnip.
99 arpwalk()
101 Visits every Layer 3 device and trys to get its ARP Cache.
102 Calls arpnip() for each device.
104 create_device(%args)
106 All %args are passed straight through to SNMP::Info except 'Class'
107 which when set turns off "AutoSpecify".
108 my $dev = create_device(
110 'DestHost' => host,
111 'Community' => public,
112 'Version' => 2,
113 'Retries' => 2,
114 'Class' => 'SNMP::Info::Layer2',
115 'VersionForce' => 1,
116 Connect to a device via SNMP::Info with a given host and community
118 string.
119 If optional "Version" and "Class" are given, no device type
121 discovery is done.
122 If a more specific device type is not found "-1" is returned. The
124 target device is probably not a network device.
125 If "VersionForce" is true, no fallback to snmpv1 will happen.
127 device_root()
129 Looks to see if the device has a master IP instead of the one
130 given. Checks for root_ip() method, then tries to lookup the
131 reverse entry for sysName.0
132 find_neighbors()
134 Finds all the CDP information on the device and stores the results
135 in device_node.
136 Adds to the @Discover_Queue
138 get_device(host)
140 Calls create_device() with a community string
141 If cached values are stored in the database for the SNMP version
143 and community strings, they are used.
144 If no cached values are available, or if they fail, then the values
146 from the config file are tried.
147 check_snmp_version(device,[version])
149 Check for a forced SNMP version by the configuration file arguments
150 snmpforce_v1, snmpforce_v2, snmpforce_v3
151 get_snmp_args(device,version,comm/user,rw)
153 Returns the args used to connect to device with version
154 get_device_rw(device[,version])
156 Returns a SNMP::Info object for a given device, using the Read-
157 Write Community Strings in the config file.
158 Returns undef or -1 on error.
160 get_subnets(device)
162 Grab netmask and ip from device interfaces. Determine device
163 subnets mathematically based upon the interface information.
164 store_modules()
166 Gets all the physical module information using Table Methods in
167 SNMP::Info.
168 Deletes the old module entries in device_module and puts in new
170 ones.
171 mac_getportmacs()
173 Fills the global %PortMAC with MAC addresses of ports already
174 discovered. This is to make sure we don't mac-suck existing ports,
175 such as VLANs.
176 macsuck()
178 Walks forwarding table for a specific device.
179 Gets mac addresses that are listed in physical ports that do not
181 have a neighbor listed. If the device has VLANs, it will walk
182 each VLAN and get the MAC addresses from there.
183 macsuck_vlans(...)
185 For certain Cisco switches you have to connect to each VLAN and get
186 the forwarding table out of it. Notably the Catalyst 5k, 6k, and
187 3500 series
188 This sub checks to see if the device supports this and then
190 interrogates each VLAN.
191 Returns number of nodes discovered in forwarding tables.
193 wireless_client_info
195 Walks Cisco dot11 client associations, if present, and stores per-
196 client association information.
197 mac_savecache({},{})
199 Does two things :
200 1. Checks for detected uplinks, warns of such and removes nodes on
202 these uplinks from additions list
203 2. Stores the found forwarding table entries to the database.
205 macwalk()
207 Grabs all the devices out of the database. Runs macsuck() on each
208 device that has layer2 capabilites.
209 send_monitor_email()
211 If there is an email address configured in netdisco.conf under
212 node_monitor_email, look for any rows in the node_monitor table
213 that are being monitored and if the mac address has arrived or
214 moved, send the appropriate email. This function only works
215 immediately after macsuck; if another macsuck happens in between
216 this will not detect the arrival. Therefore, this function is only
217 ever called from the end of macwalk.
218 set_status()
220 Sets $0 to a status string. Use sprintf-style arguments.
221 parallel_init()
223 Initializes parallelization with the maximum number of
224 simultaneously running processes set in configuration file. Creates
225 a dummy SNMP::Info object to load MIBs only once for each child.
226 Disconnects the database handle so that it's not held open across a
227 fork.
228 dispatcher(action, subroutine)
230 Multi-process dispatcher that handles the "standard" case of
231 multiple macsuck/arpnip/nbtstat. It uses Parallel::ForkManager in
232 a slightly unusual way, in that it forks off long-lived worker
233 children that service the queue themselves, similar to Apache.
234 port_control(switch,port,direction)
236 port_switch({})
237 Used to shut ports on and off and to change VLANs.
238 store_device()
240 Calls all the global methods and sends the results off to the
241 database
242 store_interfaces()
244 Gets all the interface information using Table Methods in
245 SNMP::Info.
246 Deletes the old interface entries in device_port and puts in new
248 ones.
249 store_vlans()
251 Gets all the VLAN information using Table Methods in SNMP::Info.
252 Deletes the old VLAN entries in device_port_vlan and puts in new
254 ones.
255 store_power()
257 Gets all the Power-over-Ethernet information using Table Methods in
258 SNMP::Info.
259 Deletes the old PoE entries in device_power and device_port_power
261 and puts in new ones.
262 walk_fwtable()
264 Walks the Forwarding table from the "BRIDGE-MIB" for the given
265 device, and then adds MAC addresses to the "node" table. Returns
266 the number of entries fetched.
267 NetBIOS Functions
269 nbtstat(host)
271 Connects to node and gets NetBIOS information. Then adds entries to
272 node_nbt table.
273 Returns whether a node is answering netbios calls or not.
275 nbtwalk()
277 Visits every node and trys to get its NetBIOS information.
278 Calls nbtstat() for each device.
280 Maintenance Functions
282 alias_clean()
284 Routine to clean out devices that are now listed as aliases of
285 another device. This is usually necessary after a device has been
286 merged into another one.
287 arp_dump(dir)
289 Dumps node_ip table to files arp_current and arp_archive.
290 change_device_ip(from_ip, to_ip)
292 Used to move move over all the information from one device to a new
293 IP address. First tries to discover new device, then proceeds to
294 move over old information.
295 db_clean()
297 Removes all the entries in "node" that are switch ports.
298 Checks for nodes on non existant ports and prints a warning
300 Removes nodes that are on uplink ports.
302 dev_dump()
304 Dumps out the device,device_ip, and topology info from device_port
305 to file 'devices'.
306 expire_data(type,days,archive_only)
308 "type" can be : node,device,process
309 "days" is a positive integer number of days in which an entry has
311 not been updated.
312 "archive_only" for node only.
314 Removes devices and nodes that haven't been updated in "days" days
316 or processes created "days" days ago. Process table clean up is
317 for crashed or improperly terminated jobs still in the table.
318 Called from nightly() and controlled through the "expire_*"
319 directives in the config file.
320 Cheers to Brian Wilson for his patch for the start of this feature.
322 expire_device(device,expire_nodes?)
324 Removes device from the database
325 Set second argument to true to remove all the connected nodes and
327 their IP mappings as well.
328 expire_nodes(device,archive_only,port)
330 Removes entries from node and node_ip for a given device.
331 Set port to limit the expiration to a specific port.
333 Set archive_only to 1 to archive the nodes on the device.
335 expire_nodes_subnet(subnet)
337 Subnet is in CIDR format, or any other format that Postgres likes.
338 192.168.0.0/24
340 Runs expire_ips afterwards to cleanup.
342 expire_ips()
344 Expires IPs not in use in node.
345 delete from node_ip where
347 mac not in
348 (select mac from node)
349 mac_dump()
351 Dumps the node table out to mac_current.txt and mac_archive.txt.
352 Adds a day stamp, no time-stamp.
353 netbios_dump()
355 Dumps the node_nbt table out to netbios_current.txt and
356 netbios_archive.txt. Adds a day stamp, no time-stamp.
357 nightly(no_batch)
359 Nightly maintance routine that creates backups of the device,node,
360 and node_ip tables.
361 Calls expire_data(), nmis_dump(), mac_dump(), arp_dump(),
363 dev_dump(), netbios_dump(), db_clean() and VACUUM ANALYZE
364 nmis_dump()
366 Dumps the device table out to NMIS (http://www.sins.com.au/nmis/)
367 style config file.
368 Graphing Functions
370 graph(no_batch)
372 Creates netmap of network. Calls Netdisco::make_graph() and
373 graph_each()
374 graph_each(Graph_obj, name)
376 Generates subgraph. Called from graph(). Calls graph_node().
377 Does actual GraphViz calls.
379 graph_addnode(graphviz_obj,node_ip)
381 Checks for mapping settings in config file and adds node to the
382 GraphViz object.
383 Admin Daemon
385 admin_daemon_ctl(cmd)
387 start,stop,restart,status
388 admin_daemon_status(pid)
390 Returns 0 if daemon is not running or returns pid number if
391 running.
392 pid argument is optional, used in stop function
394 admin_daemon()
396 Resident copy of netdisco to handle requests from the admin panel.
397 admin_daemon_pid(pid_to_write)
399 If not supplied arguments, Reads pid of daemon pid from
400 netdisco_daemon.pid
401 If supplied arguments, writes the pid out to that file.
403 admin_daemon_job(job_obj)
405 Runs each job. Redirects output to data/admin/job-num-date.log
406 job_obj is the sql hash object for each job.
407
409 Changes in code from 0.92 on: Copyright (c) 2003-2009 Max Baker and the
410 Netdisco Developer Team - All Rights Reserved
411 Original Code: Copyright (c) 2002,2003 Regents of the University of
413 California All rights reserved.
414 Redistribution and use in source and binary forms, with or without
416 modification, are permitted provided that the following conditions are
417 met:
418 * Redistributions of source code must retain the above copyright notice,
420 this list of conditions and the following disclaimer.
421 * Redistributions in binary form must reproduce the above copyright notice,
422 this list of conditions and the following disclaimer in the documentation
423 and/or other materials provided with the distribution.
424 * Neither the name of the University of California, Santa Cruz nor the
425 names of its contributors may be used to endorse or promote products
426 derived from this software without specific prior written permission.
427 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS
429 IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
430 TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
431 PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
432 OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
433 SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
434 LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
435 DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
436 THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
437 (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
438 OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
439perl v5.10.0 2009-11-09 NETDISCO(1)