File: README

package info (click to toggle)
netdisco 0.95-3
  • links: PTS, VCS
  • area: main
  • in suites: lenny
  • size: 1,448 kB
  • ctags: 1,395
  • sloc: perl: 3,992; sh: 648; sql: 377; makefile: 175
file content (1573 lines) | stat: -rw-r--r-- 57,985 bytes parent folder | download
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
1348
1349
1350
1351
1352
1353
1354
1355
1356
1357
1358
1359
1360
1361
1362
1363
1364
1365
1366
1367
1368
1369
1370
1371
1372
1373
1374
1375
1376
1377
1378
1379
1380
1381
1382
1383
1384
1385
1386
1387
1388
1389
1390
1391
1392
1393
1394
1395
1396
1397
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
1415
1416
1417
1418
1419
1420
1421
1422
1423
1424
1425
1426
1427
1428
1429
1430
1431
1432
1433
1434
1435
1436
1437
1438
1439
1440
1441
1442
1443
1444
1445
1446
1447
1448
1449
1450
1451
1452
1453
1454
1455
1456
1457
1458
1459
1460
1461
1462
1463
1464
1465
1466
1467
1468
1469
1470
1471
1472
1473
1474
1475
1476
1477
1478
1479
1480
1481
1482
1483
1484
1485
1486
1487
1488
1489
1490
1491
1492
1493
1494
1495
1496
1497
1498
1499
1500
1501
1502
1503
1504
1505
1506
1507
1508
1509
1510
1511
1512
1513
1514
1515
1516
1517
1518
1519
1520
1521
1522
1523
1524
1525
1526
1527
1528
1529
1530
1531
1532
1533
1534
1535
1536
1537
1538
1539
1540
1541
1542
1543
1544
1545
1546
1547
1548
1549
1550
1551
1552
1553
1554
1555
1556
1557
1558
1559
1560
1561
1562
1563
1564
1565
1566
1567
1568
1569
1570
1571
1572
1573
NAME

    Netdisco 0.95 - README

AUTHOR

    Netdisco is maintained by a team of Open Source developers headed by
    Eric Miller, Bill Fenner and Max Baker.

DESCRIPTION

    Netdisco is an Open Source web-based network management tool.

    Designed for moderate to large networks, configuration information and
    connection data for network devices are retrieved and set by SNMP. With
    Netdisco you can locate the switch port of an end-user system by IP or
    MAC address. Data is stored using a SQL database for scalability and
    speed.

    Cisco Discovery Protocol (CDP), Foundry Discovery Protocol (FDP), and
    SynOptics Network Management Protocol (SONMP) optionally provide
    automatic discovery of the network topology.

    The network is inventoried by both device model and operating system
    (like IOS). Netdisco uses router ARP tables and L2 switch MAC forwarding
    tables to locate nodes on physical ports and track them by their IP
    addresses.

    For each node, a time stamped history of the ports it has visited and
    the IP addresses it has used is maintained. Netdisco gets all its data,
    including topology information, with SNMP polls and DNS queries. It does
    not use CLI access and has no need for privilege passwords. Security
    features include a wire-side Wireless Access Point (AP) locator.

    Netdisco was created at the University of California, Santa Cruz (UCSC),
    Networking and Technology Services (NTS) department. UCSC continues to
    support the development of Netdisco by providing development servers and
    financial support. The Netdisco project is hosted by Source Forge.

    See <http://www.netdisco.org>

FEATURES

  Switch Ports

    From the web interface devices connected to switch and router ports are
    listed by MAC address. A history of which switch ports a MAC address has
    been seen at is kept. With a click the you can browse a network device
    connected to an uplink port. With another click you can disable or
    enable the switch port, logging the reason, user and date.

    * Central location to disable/enable switch ports.
        Network administrators can disable and enable ports without having
        to know enable or privilege passwords. Reasons for switching on/off
        ports are logged for end-of-the-year auditing and reporting. Non-IOS
        savvy managers can control port access from a familiar browser
        interface. This feature was designed with a University Residential
        Networks (ResNet) in mind.

        Only users you specify in Netdisco will have access to switch off a
        port. Netdisco will also not allow people to switch off uplink ports
        by accident.

    * Supports Cisco VLAN Community String indexing ("public@101")
    * MAC Address to switch port resolution
    * IP Address to switch port resolution
    * Find Switch Ports with multiple nodes attached
    * Find nodes using multiple IP addresses
    * Find nodes by vendor (using MAC address OUI)

  Easy Administration

    * Controllable through Web Interface or Command Line Interface (CLI)
    * Database store for scalability and speed (Postgresql)
    * Easily extendible to new network devices
    * User system to restrict access and features

  Network Administration and Security

    * Automatic inventory and search of network hardware
    * Administratively enable/disable switch ports from web interface with
    logging
    * Duplex Mismatch Finder
    * Find Wireless Access Points (APs) from wired-side of network
    * Layer Two Traceroute

  Reporting

    * Graphing of network topology. Clickable image-map of devices. Link
    speed shown
    * Statistics for number of actual nodes connected to network

  Inventory of Network Devices

    * by Operating System (IOS,CatOS,HP...)
    * by Model, Vendor, OSI Layer, DNS Name
    * Find device ports that are blocking (via Spanning Tree Protocol)
    * Find devices using IP's w/out DNS entries

  SUPPORTED DEVICES

    Netdisco supports any Network device that talks SNMP and has basic
    information available through MIB-II (RFC 1213). Additional
    vendor-specific information is available for a number of devices, but
    especially for Cisco, HP, and Bay devices.

    Device support is handled through "SNMP::Info" -- a Perl module that is
    an integral part of Netdisco that handles device-specific code. See the
    "Device Matrix" at <http://snmp-info.sourceforge.net> for a list of
    devices that have been tested against Netdisco. SNMP::Info can be
    extended for new families of devices relatively easily with a little
    Perl knowledge.

SUPPORT

    Please use the "netdisco-users" mailing list for all problems and
    comments.

    <http://lists.sourceforge.net/lists/listinfo/netdisco-users>

    In case of bugs, please use the Bug interface from SourceForge page at:

    <http://sourceforge.net/projects/netdisco>

GLOSSARY

    Device
        Any device connected to the network that contributes to the physical
        topology. Devices need to be accessible via SNMP. A device usually
        has multiple interfaces (ports) and can have multiple IP addresses.

    Node
        A node is anything connected to a device. Nodes are uniquely
        identified by their MAC addresses. A node may or may not have IP
        addresses associated with it.

    Macsuck
        Technical Answer : The process in Netdisco that goes out to all
        Layer-2 devices and gets the Forwarding Tables / CAM Tables. Each
        row in the table maps a MAC address to a switch port. This process
        is what makes devices show up on switch ports.

        Netdisco will attempt to detect uplink ports in case you are missing
        topology data during macsuck. Check the logs of the macsuck /
        macwalk for notifications of detected uplink ports, and add that
        data to your netdisco-topology.txt.

        Fun Answer - From Douglas M. McKeown :

        "This is where you go to a switch (Layer 2) and find all the MAC (or
        Ethernet Hardware) addresses which this device is connected to. So
        you plug your Dell into your HP Switch and that HP Switch is
        uplinked to your Core switch (not using the word router here. we're
        talking simple, physical network connections, sort of like
        electrical wires.) Well your Dell has a MAC address of let's say "A"
        and amazingly, your HP switch has a MAC address of "B" and your Core
        switch has an address of "1". Well if you Macsuck your Core switch,
        it doesn't have your Dell connected to it, but it does have "B"
        which is another switch. So you Macsuck "B" and it has MAC addresses
        for 1, B and A! You don't really Macsuck an end device (your Dell).

        So what do we know?

            - Core (1) knows about HP Switch "B".
            - HP Switch "B" knows about Core (1) and Dell "A".
            - Dell "A" knows about HP Switch "B".

        Does "1" know about "A" ? If it's a router it does. Otherwise it
        asks who has "A" and switch "B" says, I know! So 1 goes to B which
        goes to A.

        Got it?"

    Arpnip
        The process in Netdisco that goes out to every Layer-3 device and
        gets its ARP cache. Each entry in the ARP Cache maps a MAC address
        to an IP address.

        This process is what lets Netdisco map an Ethernet address to an IP
        address. Combined with the Macsuck process, Netdisco can ultimately
        resolve an IP address to a switch port.

        If you have a small network that only has layer-2 devices on it, and
        you use a Linux or BSD box as your router, you will need to install
        net-snmp on the machine, and then have netdisco discover that
        machine. Otherwise you will not be able to resolve a MAC address to
        an IP address.

    CDP / FDP / SONMP
        Having topology information is crucial for Netdisco to function. So.
        if you network does not support one of the above Layer2 discover
        protocols, you must put the information in the netdisco-topology.txt
        file.

        See "Topology Information" in this file.

        From Douglas McKeown :

        "CDP is the Cisco Discovery Protocol. Sort of an add-on for when
        switches talk to switches about who's connected to whom. CDP quickly
        tells other switches that it has switches connected. Netdisco really
        likes CDP a lot for mapping out the network and automatically
        discovering the topology. If your devices don't use CDP, then you
        need to work with the netdisco-topology.txt file to create a layout
        of your network."

        Note that FDP (Foundry) and SSOMP (Nortel/Bay) are both supported,
        and anywhere you see CDP you can assume we mean FDP and SSOMP too.

        Security Warning
            WARNING! There is a potential community string exposure when
            Netdisco is auto-discovering network equipment ("netdisco" -r).
            If a malicious host were to implement CDP and Netdisco were to
            discover that host, Netdisco would send all read-only community
            strings to that device in an attempt to add it to the topology.

            There are two main ways to avoid this exposure:

            List addresses of valid devices
                Use the discover_only and/or discover_no configuration
                keywords to control what IP addresses netdisco will be
                permitted to visit. "discover_only" is inclusive, and
                "discover_no" is exclusive; it's recommended to use
                "discover_only" if feasible.

                When using this method, check the backend log for devices
                visible via CDP but not via SNMP. These may point out the
                need to expand the range that is discoverable, or may be
                instances of this class of attack.

            Disable CDP and other discovery protocols
                This solution involves disabling CDP and other discovery
                protocols from your user-connection ports, and leaving it on
                on inter-device ports. Unfortunately, in some
                configurations, user-connection ports are inter-device
                ports, e.g., especially when you want to keep the ability to
                easily add a phone to a port that didn't have one
                previously.

                Sample "IOS" Code for above:

                 interface range fastethernet1/1-32
                  no cdp enable

                Make sure you don't disable CDP on any ports that are
                connected to other pieces of infrastructure. Also make sure
                you don't use the global command "no cdp run", since that
                will disable CDP entirely.

INSTALL

    See the INSTALL document for instructions and requirements to install
    Netdisco.

USING NETDISCO

  Components

    Netdisco has three components :

    1. Back-end
        The back-end talks to devices via SNMP. Contained in the back-end is
        the logic to create the topology, collect statistics and generate
        graphs.

        Most of the back-end is controlled by cron jobs.

        A background daemon is put resident to run maintenance tasks
        collected from the front-end. This keeps these sometimes memory
        intensive tasks and code out of the httpd processes.

    2. Database
        Netdisco uses PostgreSQL to store all its information. Careful
        abstraction of the database calls means that Netdisco can be ported
        to another SQL platform easily. Hooks to use other databases are
        present.

    3. Front-end
        The front-end operates on stored data only. This abstraction is both
        for speed and security.

        Some front-end administration tasks are put in a queue in the
        database that a daemon running from the back-end picks up and
        processes.

        The number of people using Netdisco can scale with the web server
        capacity, and will create no extra load on the devices.

  Command-Line Options

    -b || --batchmode
        Batch Mode. Redirect output to log file. Log file directory set in
        configuration file under datadir.

    -C || --configfile file
        Set Config file. Default is netdisco.conf.

    -D || --debug
        DEBUG. Sends copious information to STDOUT

    -L || --nologging
        No Log. This will not add entries to the log table.

    -n || --nodestoo
        Delete Nodes. Used with --expiredevice only.

    -N || --newonly
        New Only. On a network discovery -r, only discover found devices
        that aren't in the database.

    -P || --port port
        Port. Specify Port for removal of nodes -e.

    -S || --dumpsql
        Debug. carp() SQL commands. Sets $netdisco::SQLCARP to 1.

    -V || --archive
        archiVe nodes. Used with -e only.

  Command-Line Commands

    -a || --arpwalk
        Arp Walk. ArpNip each device that has Layer 3 capabilities.

    -A || --arpnip device
        ArpNip. ArpNip's a single device. See ArpNipper in Design.

        Devices listed in "arpnip_no" in the config file are excluded. If
        there is a "arpnip_only" entry in the config file, devices not
        listed are excluded. See the entry below.

    -B || --backup
        Backup and Nightly Maintenance.

        Removes
            Devices and nodes that are old using the "expire_*" config file
            directives (see below).

        Creates
            Archive data files for node,node_ip,device, and device_ip
            tables.

        Calls
            Database cleanup routines (-K) as well.

        Exports
            NMIS config file if nmis_dump is set.

        This routine should be run nightly.

        For a full backup run sql/pg --back to backup the whole database.

    -d || --discover device
        Discover Device.

        IP addresses and subnets listed in "discover_no" in the config file
        are excluded. If there is a "discover_only" entry in the config
        file, IP addresses and subnets not listed are excluded. See the
        entry below.

    -e || --expirenodes device
        Expire Nodes for given device. Use -V to archiVe instead of delete.
        Specify a port with -P to delete or archive nodes on a per port
        basis.

    --expire-nodes-subnet subnet
        Finds all devices in given subnet and runs expire nodes on each.
        Will display devices effected and then ask for confirmation.

        Subnet is specified in CIDR format :

            192.168.0.0/24

    -E || --expiredevice device
        Delete a device. Use -n to delete nodes as well.

    -F || --discoverfile file
        Discover Device from given File. Used to restore backed up info from
        -B, and to discover devices that are not available through topology
        information. Use -T to only import Topology Information.

    -g || --graph
        Graph. Creates graph -- both GIF and ImageMap.

        NOTE: You can safely ignore all warnings about "size too small for
        label".

        Make sure you have a relatively new version of GraphViz. You need a
        newer version of GraphViz if you get an error similar to:

          Creating CMAP : /usr/local/netdisco/html/netmap.map
            warning, language cmap not recognized, use one of: ps hpgl pcl mif...

    -h || --help
        Prints out command line usage.

    -i || --changeip old_ip new_ip
        Change IP address of device. Creates new entry, removes old one and
        moves nodes over to the new one.

    -I || --expireips
        Expire IP Addresses from node_ip table. This will delete entries
        from the node_ip table that are not matching entries (MAC Addresses)
        found in the node or device_port tables.

    -k || --cleanalias
        alias klean-up. DANGEROUS. Deletes from the device table any IP
        address that is found as an alias in the alias table.

    -K || --cleannodes
        Database Node Klean-up. Permanently deletes nodes matching:

        1. MAC Addresses that are Switch Port Addresses
        2. MAC Addresses that are listed on non-existent ports
        3. MAC Addresses that exist on ports with topology information
        (uplink ports)

    -m || --macwalk
        Mac Suck each device in the database that has Layer 2 capabilities.

    -M || --macsuck device
        Mac Suck given device only.

        Devices listed in "macsuck_no" in the config file are excluded. If
        there is a "macsuck_only" entry in the config file, devices not
        listed are excluded. See the entry below.

    -O || --oui
        Import OUI information from oui.txt

    -p || --daemon [start,stop,status,restart]
        Control the Admin Daemon. Takes arguments
        (start,stop,status,restart).

    -r || --discoverall root_device
        Walk the network with the given root. Use -N to discover new devices
        only. Given root device will always be discovered.

    -R || --refresh
        Refresh devices. Will run a discover (-d) for each device in the
        database.

    -T || --topofile
        Import Topology Data. Will import manual topology data stored in
        file specified by configuration option topofile . Use -F to specify
        a different file from the command line.

        It is not necessary to do this after every change. This is only a
        convenience switch.

    -u || --user [user] [password] [port_control?] [admin?]
        Add or Change a User. Supply all four arguments (user pw
        port_control admin) for command-line control, or supply less for
        interactive prompts.

        It's better to use interactive prompts so that the password doesn't
        get stored in your shell history file and exported to the process
        table.

    -v || --version

  Features

    Admin Daemon
        The admin daemon is a copy of "netdisco" that runs in the
        background. From the web "Admin Panel", jobs are put in a queue in
        the database. The daemon picks up these jobs and executes them from
        the back-end as user "netdisco". The daemon is restarted daily in a
        cron job, or can be manually started as root :

            su - netdisco -c "/usr/local/netdisco -p restart"

    Port Info / Jack Search
        This feature integrates Netdisco with other databases that have port
        info.

        Port Info was designed around data coming out of a Pinnacles
        database at UCSC, and might prove to be site-specific. However, see
        "port_info.html" for a good example of how to access other databases
        using the "netdisco.pm" SQL routines.

        Enable this feature by setting "port_info" to true in
        "netdisco.conf"

    Port Control
        Port Control allows a user of Netdisco to administratively turn a
        port on or off.

        To do this the back-end requires a read-write community string for
        the device in question. The admin daemon must also be enabled.
        Netdisco keeps a log for each port holding information about why a
        port was turned on or off.

        A reason for turning switch the port is chosen from a list to
        provide future audits of admin activity. The user and IP address of
        the request are stored. To change the default reasons, modify the
        %PORT_CONTROL_REASONS hash in "netdisco.pm"

        Optionally if the "portctl_email" setting is set in "netdisco.conf",
        an e-mail is sent out with a notification of the switching. Locally
        at UCSC that e-mail is sent to an administrative mailing list.

        To turn this feature off uncheck the "Port Control" checkbox from
        all users in the "Admin Panel".

        By default Netdisco will be allowed to shut off

            - Switch Ports
            - IP Phones
            - Router Ports that are NOT uplinks

        By setting certain config file directives you can allow Netdisco to
        shutoff uplink ports and VLAN interfaces. But this is REALLY NOT
        RECOMMENDED. See below for the required commands.

    Web Console
        The Web Console allows netdisco to front-end the web interface of a
        switch or router. Traffic can then be routed over https, through
        Netdisco's web server. An additional security layer is added by
        requiring the user to be logged into Netdisco. The normal security
        measures used by the device's web server are still active.

        The Web console is a reverse proxy that runs on Apache. You must
        enable it in "netdisco_apache.conf" and "netdisco_apache_dir.conf".
        The add devices and models to the configuration lines
        "web_console_vendors" and "web_console_models" in "netdisco.conf".

  Netdisco Maintenance

    Refreshing a device
        To refresh or discover a device and its ports, use the -d command:

            netdisco -d mydevice

    Importing Topology Information
        It is not necessary to import the topology information after
        changing netdisco-topology.txt. You should however restart the admin
        daemon. The topology text file is re-parsed each time you run
        netdisco.

        As a convenience you can use the topology file to quickly seed
        Netdisco with devices. To import all the topology information at
        once make sure the topology filename is set in "netdisco.conf" and
        use the -T command:

            netdisco -T

    Aborting a process of Netdisco
        Hit Ctrl-C if you are running a netdisco process, or send the job
        the INT signal. The job can cleanup after itself, write out its
        stats and log entries.

            kill -INT jobpid

        There is currently no way to stop a job inside the Admin daemon.
        Send the daemon an INT signal and it will terminate after its
        current job has completed.

    Changing the IP Address of a Device
        If a device is being replaced with a different device and a
        different IP, see "Deleting a Device" below.

            netdisco -i old-ip-address new-ip-address

        Changing the IP address of a device will:

        1. Discover the new device
        2. Remove Old Device Entry, port, and aliases
        3. Move the old nodes to the new device.

    Auto-Deleting Old Data From the Database
        In order for Netdisco to be self-maintaining data has to be taken
        out of the database as well as put in. The following config file
        directives are used to auto-prune stuff from the database :

        expire_devices
        expire_nodes
        expire_nodes_archive

        See each item's entry in the "Config File" Section below for more
        details.

        The expire data routines are called from the -B/Backup routine,
        which should be running nightly via cron.

    Deleting a Device
        To delete a device use the -E command followed by the device name or
        IP. Set -n to delete all the nodes seen on that device as well

        This is rather permanent. Make sure you run -Backup before you do
        this.

    Deleting Nodes
        Nodes consist of two components -- the switch port to MAC address
        mapping in the "node" table, and the MAC address to IP mapping in
        the "node_ip" table.

        To remove nodes from a switch, use the Admin Panel on the web side
        and choose either "Delete Nodes" or "Archive Nodes". Archiving nodes
        will set the archive bit so that the data will be available, but not
        always showing. You can also delete nodes from the command line
        using the -e command with or without the -V flag.

        Database Cleanup -K will delete nodes that seem to be extraneous.
        See -K for more details.

        Once you have cleared out nodes from a switch, then run -I to remove
        unused node to IP mappings.

        This is rather permanent. Make sure you run -Backup before you do
        this.

    Adding / Changing Users
        The easiest way to add a user is to use the "Add User" form in the
        Admin Panel. After first installing Netdisco you need to add an
        admin user by running -u.

    Migrating the Users table to a new host
        If you are moving your Netdisco install over to another machine and
        you want to keep your users table, here is the process :

            source$ pg_dump -a -d -U netdisco -t users netdisco > user_dump.sql
            source$ scp user_dump.sql dest:

            dest$ cd /usr/local/netdisco/sql
            dest$ ./pg /path/to/user_dump.sql

    Localhost (127.0.0.1) is showing up on CDP Links
        See "How the Switch Selects the IP Address To Include in Outbound
        CDP Packets" in
        ftp://ftp.hp.com/pub/networking/software/59692375_e1.pdf

    Device Model comes up as 'Products.'
        The device is probably newer than your Cisco MIBs. Redownload
        <ftp://ftp.cisco.com/pub/mibs/v2/v2.tar.gz> and install these newest
        mibs into /usr/local/share/snmp/mibs.

    Things are getting Really slow
        For some reason over here at UCSC, things get real slow in Postgres
        after a while. Even though we are doing frequent VACUUM's on all the
        data, it seems to be dragging down after a while.

        This turns out to be an INDEX bloat problem on Postgres versions
        less than 7.4. Recently doing this on a Postgres 7.3 install changed
        the amount of space that Netdisco's database was using from 16G to
        400M !!!

        In order to fix this we do a "VACUUM FULL ANALYZE VERBOSE" and
        "REINDEX" from "pg". This command locks each table before it does
        the VACUUM, and therefore can be more thorough. It's a good idea to
        take netdisco down temporarily while you do this. I do this about
        once a month, or when I notice it dragging down. Use "Netdisco
        Statistics" as a good metric of things slowing down. This may get
        fixed with changes in VACUUM in Postgres 7.4 and above.

        Procedure for doing a vacuum full (as root):

        1. Shutdown the admin daemon
                /usr/local/netdisco/bin/netdisco_daemon stop

        2. Clear the cron tab for user netdisco
                crontab -u netdisco -r

        3. Comment out the netdisco config file Includes in httpd.conf
        4. Restart Apache
                /usr/local/apache/bin/apachectl graceful

        5. Check to see if any netdisco jobs are running and wait for them
        or kill them
                ps
                killall netdisco

        6. Run REINDEX and VACUUM FULL
            Before:

                df -h
                /usr/local/netdisco/sql/pg
                    # before comparison :
                    select relname, relpages from pg_class order by relpages desc;

                    REINDEX TABLE node;
                    REINDEX TABLE node_ip;
                    REINDEX TABLE device;
                    REINDEX TABLE device_port;
                    REINDEX TABLE device_port_log;
                    VACUUM FULL ANALYZE VERBOSE;

                    # after comparison :
                    select relname, relpages from pg_class order by relpages desc;
                    \q

            After:

                df -h

        7. Restart Postgres (just for fun)
                /usr/local/etc/rc.d/010.pgsql restart 

            OR

                /etc/rc.d/init.d/pgsql restart

            OR

                /etc/rc.d/pgsql restart

        8. Uncomment lines in httpd.conf
        9. Restart Apache
                /usr/local/apache/bin/apachectl graceful

        10. Reload crontab for user netdisco
                crontab -u netdisco /usr/local/netdisco/netdisco.crontab

        11. Restart Admin Daemon
                /usr/local/netdisco/bin/netdisco_daemon start

    Clearing the Admin Queue
        If your admin queue is just getting too long and you want to clear
        it you can do it by just dropping the table and readding it.

            cd sql
            ./pg admin.sql

  Topology Information

    Topology information is crucial to Netdisco's performance. It allows the
    application to know which ports are uplink ports and which have
    connected nodes. Ports that are uplink ports that are not marked so in
    Netdisco will appear to steal MAC address entries from their rightful
    ports. So it is critical to use the topology file and CDP/FDP/SONMP to
    maintain a topology.

   Autodetection of uplink ports

    During macsuck if Netdisco finds the MAC address of a known device or
    switch port, then that port is marked as an uplink. Nodes will not
    collect at these switch ports, and a warning message will be printed.
    Check the logs of your macsuck and macwalk jobs in order to find and
    correct autodetected uplink ports. Add these ports to your
    netdisco-topology.txt file.

   Manual Topology Information

    Netdisco will auto-discover the layer-two topology of a network using
    CDP. However, many networks have parts of the topology that are not
    covered by CDP.

    Use the manual topology file "netdisco-topology.txt" to supply the
    layout of the network if your network has devices that don't talk CDP or
    misreport information.

    The manual topology file only requires one side of the data to be
    entered. Both directions of a link will be forced to the given data if
    one side is listed.

    File Format

    The format of the manual topology consists of four types of lines:

    #comment
        Comments are delimited with a "#" They can happen on any line.

    routername
        Any line that does not start with "link:" or "alias:" is assumed to
        be a the DNS name or IP address of a network device.

    link:
        Lines that start with "link:" connect two devices together. The
        format is

            link:outgoing port,destination device,Destination port

        The outgoing port belongs to the device listed above the "link:"
        line.

        The Destination Device and Port tell Netdisco who is on the other
        end of this link. The device can be a DNS name or an IP Address.

        NOTE: The port names must match exactly how Netdisco sees it. Go to
        the device and check it out. You might think of it as "port 1" but
        Netdisco might think of it as "RMONPort26onunit1".

    alias:
        Not implemented for output. The backup file will have these lines
        just for informations' sake. Alias IPs on a device are found during
        discovery.

        Many network devices like routers have multiple IP addresses
        assigned to them. If the device cannot or does not supply this
        information to Netdisco in a standard way, you can add IP addresses
        used here.

    White space in the file (except for line breaks) is ignored. Tabbing
    over before "line:" lines makes it easier to read, but is not required.

    File Uses

    Some reasons the manual topology file is used:

    1. Man in the Middle
        Let's say you have two CDP speaking devices with a non-CDP speaking
        device in between them

            [Cisco] ---> [Bay] ---> [HP]

        The Cisco and HP devices (CDP speakers) find each other and the Bay
        device never appears. You would then have to add these lines to the
        topology file:

            ciscoswitch.my.company
                link:EtherNet0/1,bayswitch.my.company,25
            bayswitch.my.company
                link:26,hpswitch.my.company,J3

        This tells Netdisco that port "Ethernet0/1" on "ciscoswitch" is
        connected to Port 25 on "bayswitch". Then in turn Port 26 on
        "bayswitch" is connected to port "J3" on "hpswitch".

        A note about devices that are *CDP Aware* and that implement CDP:

        *CDP Aware* devices are devices that probably do not speak CDP
        (probably for legal reasons) but that are smart enough not to
        forward CDP packets. Cisco devices that have CDP disabled are
        usually still *CDP Aware* and will not forward the packets.
        Man-in-the-middle situations occur when the device both does not
        speak CDP and is not *CDP Aware*.

    2. Isolated Network Segment
        If you have a segment of your network that is not connected
        directly, or connected through a non physical link like a VPN, then
        you might fudge an entry to connect that segment of the network with
        the main one.

    3. Attach a non-CDP speaking device
        Anywhere a device that does not supply topology information is
        connected to the network, an entry must be added in the manual
        topology file.

  Cron Jobs

    Netdisco is controlled via cron jobs. Jobs are run as user "netdisco".
    Multiple jobs can be run at once.

    The default jobs are :

    * MacSuck - Every 2 hours MacSuck all the devices in the database.
    * ArpNip - Every 2 hours ArpNip all the devices in the database. (Offset
    from Macsuck by 1 hours)
    * Refresh Devices - Once a day refresh device information.
    * Backup - Once a day backup information.
    * Graph - Once a day re-create the graph.
    * Walk Network - Once a week (Wed @ 14:00) try and discover new devices.
    * Restart Admin Daemon - Once a day just for good measure.

Config File

    The settings in "netdisco.conf" are used both in the back-end and the
    front-end.

    When you make a change in the config file that is used in the web front
    end, you must reload apache. The config information is shared between
    processes for speed and memory performance.

        su - -c "/usr/local/apache/bin/apachectl restart"

    Multiple config files can be used in the back-end by calling Netdisco
    with the "-C" option:

        netdisco -C myotherfile.conf

  General Items

    domain
        STRING. Trimmed from all DNS names viewed. Leave blank to show all
        domain names. Add a dot in front of your value :

            .ucsc.edu

    home
        PATH. Full path to where netdisco lives. Is the root path for all
        other files and paths.

  Database Maintenance

    New in version 0.93 these directives are included to help make Netdisco
    more self-maintaining.

    Setting these will result in permanent data removal.

    expire_devices
        DAYS. Devices that have not been refreshed in this number of days
        will be removed. All nodes connected to this device will be removed
        as well.

    expire_nodes
        DAYS. Nodes that have not been refreshed in this number of days will
        be removed from the database. Archived and non-archived nodes are
        removed. This includes SwitchPort/MAC and MAC/IP mappings.

    expire_nodes_archive
        DAYS. Archived data for switch-port/MAC and MAC/IP mappings older
        than this number of days will be removed.

  Back-End Items

    arpnip_no
        LIST:string. Devices that won't be arpnipped. See "bulkwalk_no" for
        syntax. If you have any layer-3 devices that have been discovered by
        netdisco but are using proxy-ARP as a way to get to other devices,
        place them here. Alternately, if you have many proxy-ARP clients but
        one (or a handful of) central device with all of the proper ARP
        info, put that in "arpnip_only".

    arpnip_only
        LIST:string. If present, only arpnip these devices. See
        "bulkwalk_no" for syntax.

    compress
        EXECUTABLE. Full path and command line arguments to the compression
        program used in compresslogs

    compresslogs
        BOOLEAN. Compress log files? See compress entry above.

    datadir
        PATH. Full or relative path to the directory that backups and logs
        will be stored in

    discover_no
        LIST:string. IP addresses in this list will not be visited during
        discovery. See bulkwalk_no for syntax, except that only hostnames,
        IP addresses and subnets are valid.

    discover_only
        LIST:string. If present, discovery will be limited to only IP
        addresses in this list. If you have a management VLAN, put that
        subnet here to avoid discovering user devices. See bulkwalk_no for
        syntax, except that only hostnames, IP addresses and subnets are
        valid.

    ignore_private_nets
        Not fully implemented.

        BOOLEAN. Set to true to ignore aliases that are part of private
        nets:

            10.0.0.0/8 172.16.0.0/16 and 192.168.0.0/24  

    logextension
        STRING. The extension to add to log files.

    macsuck_bleed
        BOOLEAN. Set to true will let nodes accumulate on uplink ports
        without topology information. This is a debug option to help you
        figure out your topology and generally should not be set.

    macsuck_no
        LIST:string. Don't macsuck these devices. See "bulkwalk_no" for
        syntax.

    macsuck_only
        LIST:string. If present, only macsuck these devices. See
        "bulkwalk_no" for syntax.

    macsuck_no_vlan
        LIST:Strings. Comma separated list of VLAN names not to visit when
        MACsucking.

        This option was used to speed up MACsucking on certain Cisco
        Catalyst family devices where you have to connect to each VLAN with
        SNMP to get the forwarding tables. Certain default VLANs will not
        answer to SNMP, and Netdisco has to wait for them to timeout.

        VLANs listed here are overrided regardless of macsuck_all_vlans
        value.

    macsuck_timeout
        SECONDS. Timeout for devices when mac sucking.

    macsuck_all_vlans
        BOOLEAN. Set to macsuck all VLANs, not just the ones that are being
        used on ports.

        This is a debug option. Set this if you think that the option of not
        macsucking VLANs that aren't in use on device ports is some how
        interfering.

        Setting this would revert macsuck to the same behavior as 0.93 and
        before.

        Does not override macsuck_no_vlan.

    nbt_days
        DAYS. The maximum age of a node for it to be checked for NetBIOS
        information. Default 7.

    nmis_dump
        FILENAME. Set this option to have nightly() (-B) dump an NMIS
        <http://www.sins.com.au/nmis> style Config file. Warning, this file
        will contain SNMP Community strings.

        Optional Override options are :

        nmis_group
            STRING. Group to use with nmis_dump. Default "Network"

        nmis_role
            STRING. Role to use with nmis_dump. Default "core"

        nmis_collect
            STRING. Collect option to use with nmis_dump. Default "true"

        nmis_active
            STRING. Active option for nmis_dump file. Default "true"

        nmis_net
            STRING. Net identifier to use. Default "lan"

        nmis_port
            INT. SNMP Port to list in nmis_dump file. Default 161

    reverse_sysname
        BOOLEAN. Turn this on to have Netdisco do a reverse lookup of the
        sysName.0 field to use as the management IP address for a device.
        See bug 810939 and device_root() for more info. Default "false"

    topofile
        FILE. Full path of the file that contains manual topology
        information. Defaults to netdisco-topology.txt

    timeout
        SECONDS. Timeout for refreshing or discovering a device

   Admin Panel

    daemon_bg
        BOOLEAN. Run daemon in the background?

    daemon_pid
        FILE. Filename for the pid file used by admin daemon. Must be
        writable by daemon user.

    daemon_poll
        SECONDS. Time to wait to check for new items in the queue.

   Database Settings

    The five database settings are "db" , "db_user", "db_pw", "db_opts", and
    "db_env".

    You can run multiple database types in Netdisco. See "port_info" for an
    instance of this.

    For each of the above settings, the database shortcut name (you choose)
    is inserted after "db".

    Postgres is the required first database, and uses the short name "Pg".

    The following lines must be added :

    db_Pg
        STRING. Database connect string to give to DBI.

        Default : "dbi:Pg:dbname=netdisco"

    db_Pg_user
        STRING. Database user

    db_Pg_pw
        STRING. Database Password

    db_Pg_opts
        HASH. Options to add to the connect string.

        Default : "PrintError => 1, AutoCommit => 1"

    db_Pg_env
        HASH. Environment variables to be set before running database calls.
        Separate multiple entries with commas.

        Mainly used for Oracle.

        Default : not set.

        Example :

         db_Oracle_env  = ORACLE_HOME => /usr/local/oracle7, ORACLE_STUFF=>1

   SNMP Settings

    bulkwalk_off
        BOOLEAN. Set to true to use GETNEXT instead of BULKWALK for every
        device. This slows things down, but might be necessary for problem
        devices.

        Other solutions include addding " sub bulkwalk_off { 1; } " to the
        device class that is misbehaving in SNMP::Info. This will turn off
        bulkwalk for a class of devices, not all.

        Also see bulkwalk_no to turn BULKWALK off on a per-device or device
        class level.

        Default is on. SNMP::Info 1.0 or higher required.

    bulkwalk_no
        LIST:STRING. A comma separated list of devices to not bulkwalk

        This list can take five different inputs:

        Hostname or IP
            Simply put the device's name or IP address in the list.

                switch1, switch2, switch3

        model:regex
            Add an entire model type for excluding from bulkwalking.

            This can be a simple string like 6500 or it could be a regular
            expression like "(2512|65\d\d)". The regex must match the whole
            string (it's anchored).

        vendor:regex
            Add an entire vendor type for excluding form bulkwalking.

            This can be a simple string like "hp" or it could be a regular
            expression like "(cisco|hp)". The regex must match the whole
            string (it's anchored).

        Subnet
            You can exclude a whole subnet of devices from bulkwalking. Use
            CIDR notation.

             128.1.0.0/16

        Blanket Wildcard
            You can use a single asterix "*" to specify that all devices not
            be bulkwalked.

    bulkwalk_repeaters
        INT. Sets MaxRepeaters on BULKWALK operations. See "perldoc SNMP"
        for more info.

        Default is 20. SNMP::Info 1.0 or higher required.

    community
        LIST:STRING. A comma separated list of community strings to try on
        each device.

    community_rw
        LIST:STRING. OPTIONAL. A comma separated list of Read-Write
        community strings.

        This is only necessary if you turn on the "port_control" command.

    mibdirs
        LIST:STRING. A comma separated list of directories to search for MIB
        files.

    nonincreasing
        BOOLEAN. Setting this to true will allow the bulkwalk of devices
        that have tables with non-increasing OIDs. The default is to not
        allow this behavior to prevent problem devices from looping
        indefinitely. Requires Net-SNMP 5.3 or higher.

        See patch # 1364650 in Net-SNMP or bug # 1176130.

    snmpforce_v1
        LIST:STRING. A comma separated list of devices. Forces matching
        devices to use SNMPv1

        See bulkwalk_no for syntax.

    snmpforce_v2
        LIST:STRING. A comma separated list of devices. Forces matching
        devices to use SNMPv2c

        See bulkwalk_no for syntax.

    snmpforce_v3
        LIST:STRING. A comma separated list of devices. Forces matching
        devices to use SNMPv3. SNMPv3 is not fully supported yet but could
        probably be made to work.

        See bulkwalk_no for syntax.

    snmpver
        INT. Default version of SNMP protocol to connect with.

    snmptimeout
        INT. Settings for 'Timeout' field passed to SNMP::Session.
        Micro-seconds before retry, Default 1000000 micro-seconds = 1
        second.

    snmpretries
        INT. Settings for 'Retries' field passed to SNMP::Session

  Port Control

    portctl_email
        EMAIL. Address that reports of use of "Port Control" are sent to.

    portctl_nophones
        BOOLEAN. Set to True to make sure an IP Phone port never can be
        turned off/on. Default false.

    portctl_timeout
        SECONDS. Amount of time to wait for a response from the admin
        daemon.

    portctl_uplinks
        BOOLEAN. Set to True to allow Netdisco to be able to disable
        Uplinks. (Router Interfaces too)

        Default False.

        EXTREMELY VERY DANGEROUS - Turning off uplinks will take out chunks
        of your network.

    portctl_vlans
        BOOLEAN. Set to True to allow Netdisco to be able to disable VLAN
        interfaces.

        Default False.

        EXTREMELY VERY DANGEROUS - Turning off a VLAN could take out most of
        your network.

    vlanctl
        BOOLEAN. Set to True to allow Netdisco to be able to change the
        default VLAN on an interface.

  Web Settings

    port_info
        BOOLEAN. Turns on the "Port Info" and "Jack Search" features.

    secure_server
        BOOLEAN. If a secure server is present.

        Requires web login, password changing and all admin functions to be
        run in secure space.

    web_console_models
        LIST:STRING. Comma separated list of models that want to use the Web
        Console

    web_console_vendors
        LIST:STRING. Comma separated list of vendors that use the Web
        Console.

    webpath
        PATH. URL Path added to the beginning of links on the web front-end

    websession
        MINUTES. Amount of time a session lasts before someone has to login
        again.

    apache_auth
        BOOLEAN. Whether to use Apache-based authentication. If this is
        configured both here and in netdisco_apache_dir.conf, then logins
        will trust the REMOTE_USER set by Apache. If the user is found in
        the user database, then the appropriate privileges are applied; if
        the user is not found then they have access but no port control or
        admin access. There is another link on the sidebar, "Netdisco Login"
        to log in using the netdisco user database.

   Graph Settings

    edge_color
        STRING. Default color for link between devices.

    graph
        FILE. Full path and name to the GIF graph of the network. Path
        should be the same as in the "netmap.html" component.

    graph_bg
        STRING. Background color for the graph.

    graph_color
        STRING. Text color for the graph

    graph_epsilon
        INT. Sets the "epsilon" attribute in "GraphViz" used to control the
        graph solver. Set to an integer value. This will improve the mapping
        and visual quality of them graph. Each integer step can mean an
        exponential time increase in the solving of the graph.

    graph_clusters
        BOOLEAN. Creates clusters of nodes based on their location field.
        Best with graph_layout "fdp". Only use if all or most devices in a
        given location have the same location string.

    graph_layout
        STRING. Choose program to render graph with. Valid options are
        "neato", "twopi", "circo" and "fdp".

    graph_fontpath
        STRING. Path for graphviz to find font files to be used for
        node_font. Defaults to home.

    graph_map
        FILE. Set to Full path and name to the ISMAP data for the network.
        Path should be the same as in the "netmap.html" component.

    graph_nodesep
        FLOAT. Node Separation (in inches) of nodes in graph.

    graph_overlap
        BOOLEAN. Parameter passed to "GraphViz" for the "overlap="""
        feature.

    graph_png
        FILE. Full path and name to the PNG graph of the network. Path
        should be the same as in the "netmap.html" component. Use this if
        you prefer not to use GIF, or if your graphviz binary doesn't
        support GIF, reporting an error similar to "Renderer type: "gif" not
        recognized. Use one of: [...png...]".

    graph_ranksep
        FLOAT. Rank Separation of elements in graph.

    graph_ratio
        FLOAT or STRING. Graph's aspect ratio, may be a floating point
        number, or one of the keywords fill, compress, or auto.

    graph_raw
        FILE. Set to create the raw (.dot) graph file as well.

    graph_splines
        BOOLEAN. Turn on GraphViz's spline engine? (Is very processor
        intensive).

    graph_svg
        FILE. Set to create an SVG version of the graph. Requires GraphViz
        0.8 or greater.

    graph_timeout
        MINUTES. Time to allow "neato" to try and solve the graph. Default
        60min.

    graph_x, graph_y
        FLOAT. The X and Y dimensions of the graph in inches. To convert to
        pixels, times by 100 (96 actually). So the default values of 30x30
        will give you a graph that is about 3000x3000 pixels wide.

    node_fillcolor
        STRING. Default background color for device

    node_fixedsize
        BOOLEAN. True keeps the box size small and fixed (for huge graphs);
        false allows the box to be sized to fit the text inside. Default
        TRUE.

    node_font
        FILE. Name of the True Type Font used for label of node. Exclude
        .ttf in name.

    node_fontcolor
        STRING. Color of text

    node_fontsize
        FLOAT. Size of text in Pixels. Note that for the graph_overlap=scale
        option, the font gets scaled down and so an oversized font is used.

    node_map
        STRING. Colon separated list of values. Multiple node_map entries
        can exist. Entry is in format:

            Variable:Regular Expression:Attribute:Value:Key String:Key Title

        Variables that you can use include : label,ip

        Attributes can be any node attribute usable in GraphViz, such as
        fillcolor and color

        Examples:

            label:cat(?!-g):fillcolor:blue:cat:Blue Box - Catalyst Switch

        If the label (dns name) matches cat, but not cat-g, make it blue,
        with an entry in the key like "[cat] Blue Box - Catalyst Switch"

            ip:^169\.233:color:yellow:node:Yellow Border - ResNet

        If the IP address of the device starts with 169.233, then make the
        border around the device yellow, with an entry in the key like
        "[node] Yellow Border - ResNet".

        You may leave off Key String and Key Title to get no entry in the
        key for this color combination. This can be useful to get only one
        key entry when using multiple node_map entries with the same
        attribute/value.

    node_problem
        STRING. Color to use for devices that are not accessible

    node_shape
        STRING. Default shape for device, normally box.

    node_style
        STRING. Default style of device, normally filled.

    root_device
        STRING. IP address of a device to be used as the "center" of the
        graph.

DESIGN

  Design Goals

    * Use of SNMP Leaf Names only; No OIDs
    * Easily extendible to new devices. No device-specific hacks in logic
    * Modular back-end database front-end setup
    * Security. Front-end abstraction from device manipulation means
    sensitive network devices are not exposed to a web interface .
    * Data Archiving. Data structures and backup routines to provide online
    and offline storage of network structure and usage.
    * Highly Configurable. Extract out all possible options to netdisco.conf
    and avoid site-specific code.
    * Administration available on both command line and web interfaces.

  Back-End Components

    netdisco.pm
        Perl Module that holds all the SQL interaction routines as well as
        some helper routines. Used by both the back-end and front-end.

    SNMP::Info
        Perl Modules created for this project that are used to provide the
        interaction between the device and Netdisco over SNMP. All
        device-specific changes are done in these modules.

    Network Walker
        Using a device as a starting point (root), the walker then tries to
        visit every device directly connected to the starting point.
        Neighboring devices are found with CDP.

    ArpNipper
        The ArpNipper is visits each discovered device with Layer 3
        capabilities. Each device's ARP Cache is read and the IP address to
        MAC address translation is stored in the node_ip table.

        The original ArpNipper was written by Jim Warner at UCSC.

    MacSucker
        The MacSucker visits each device with Layer 2 capabilities. Each
        device's Forwarding Table is read. MAC addresses that are on ports
        without a physical mapping (virtual ports) are skipped. MAC
        Addresses on ports with a neighbor recorded are skipped (uplink
        ports). MAC Addresses that are actually switch ports are skipped.
        The remaining MAC addresses are recorded as nodes in the nodes
        table.

        If the device supports the v_name() call, and has VLANs, then the
        MacSucker tries to connect to each VLAN and macksuck() each VLAN.
        This is required for some devices like the Cisco Catalyst 5000,
        3500, 1900, 6500 series.

        A few speedups are implemented for the devices that require each
        VLAN to visited:

        macsuck_no_vlan
            This config file directive lists VLANs that exist in every
            device by default but do not ever have MAC addresses attached to
            them.

        macsuck_no
            Use this config file directive to exclude problem devices.

        Macsuck only happens on VLANS listed under ports
            (New 0.94) Many VLANs may be on the device or in the vtpdomain,
            but only a few of them may be in use on device_ports. Macsuck
            will not try to visit the VLANs that are not in use on device
            ports. See macsuck_all_vlans to override this.

        The original MacSucker was written by Mark Boolootian at UCSC.

    Helper Routines
        The 40+ routines for creating backups, logging, etc.

        Browse the source code or check out netdisco-api for more info.

  Database

    Netdisco uses PostgreSQL as its database store. Indexing is used heavily
    to speed up queries and facilitate large data sets. See the "sql/"
    directory and INSTALL for more information.

   SQL Tables

    admin
        Queue for admin control panel tasks to be sent back and forth from
        the front-end.

    device
        Holds device information. Each device is identified by unique IP
        Address.

    device_ip
        Holds alias IP Addresses for devices. Each device can have multiple
        IP's stored in this table. The master IP address is either taken
        from SNMP information or from the reverse DNS entry of the device
        name. Also used to link a certain alias to a port.

    device_port
        Holds the interface (port) information for each device. One row for
        each interface exists with information about the port status.

    device_port_log
        Contains log entries for port_control, tool used for
        administratively enabling and disabling ports.

    device_port_ssid
        Holds SSID and channel information for wireless access points.

    log Holds log entries for human use.

    node
        Holds an entry for each MAC address connected to the network that
        isn't a device. Tells on which switch port the node was seen, and
        when it was seen there. Also holds the archived data on node
        location. Archived data has the column ''active'' set to false. Data
        comes from MacSucker

    node_ip
        Maps a MAC Address to an IP address. Has no notion of where this
        node was seen. Keeps time stamps of when this is from. Data comes
        from ArpNipper. Archived data is similar to the node table, where
        ``active'' is set to false for archived data.

    sessions
        Web sessions created by MasonX::Request::WithApacheSessions. Stores
        information about a current session in the global $m->session hash
        under mason.

    oui Populated with data from oui.txt Oui.txt contains the
        Organizationally Unique Identifiers (OUI) that map a MAC address to
        a vendor. The database is controlled by the IEEE. See INSTALL for
        more information.

    users
        User information for web front end.

THANKS

    I would like to thank the following people for their contributions to
    Netdisco :

    Mark Boolootian (Through who's ideas Netdisco was born and shaped)
    (UCSC), Jim Warner (UCSC), Mike Hunter (UCB), Brian Wilson (NCSU),
    Bradley Baetz (bbaetz), David Temkin (sig.com), Edson Manners (FSU),
    Dmitry Sergienko (Trifle Co, .ua) Remo Rickli (PSI, Switzerland),
    Jean-Philippe Luiggi (sagem.com), A.L.M Buxey (Loughborough University,
    UK), Kevin Cheek (UMICH), John Bigrow (bnl.gov), George Pavel
    (llnl.gov), Charles Goldsmith (CompUSA), Douglas M. McKeown
    (saintmarys.edu), Revital Shvarzman (York U, Ontario), Walter Gould
    (Auburn U), Lindsay Druet and Colin Palmer (U of Waikato, Hamilton NZ),
    Dusty Hall (Auburn U), Jon Monroe (center pointe), Eric Miller
    (jeneric).

    As well as these people for their donations :

     Richard Silver (East Alabama Medical Center)
     Linda Rosewood (UCSC)
     "6pax4max!","31337" (???)
     Dusty Hall     (Auburn University)
     Walter Gould   (Auburn University)
     Frank Chatham  (Auburn University)

    And probably lots of other people I forgot to put in here. Not to
    mention the authors and communities of all the other software that
    Netdisco is built upon.