Archived - How do I discover what is on my network via the command line?

Auto Discovery details

Running auto discovery from the command line

Usage

Syntax

To set the timeout parameter

To set the number of threads

To write a configuration file

To specify an IP address

Files

With ENA, you can both schedule and manually run automatic discovery of the devices on your network from the command line. You can also run auto discovery via the UI.

Auto Discovery details:

Running auto discovery from the command line:

1. You can configure when autoDiscovery runs through provost.conf. When autoDiscovery starts, and every subsequent minute whilst it is running, it will check the value of automatic in the autoDiscovery section of entuity.cfg. When it is set to:
   • 0 - autoDiscovery is not automatically started.
     • When it is already running having been manually started, then this setting is ignored.
     • When it is already running having been automatically started, then autoDiscovery is stopped.
   • 1 - autoDiscovery runs. It finds devices on a network by pinging every IP address on each specified network.
     
     
2. autoDiscovery finds devices on a network by pinging every IP address on each specified network, and finding further subnets using SNMPv1/v2c and SNMPv3. By default, autoDiscovery:
   • does not search new subnets unless you use -follow.
   • does not search the local subnet when you include addresses. To search the local subnet, use -local.
   • command line values take precedence over any configuration file values, apart from when:
     • including addresses.
     • excluding addresses.
     • specifying port and community strings where the values are combined.
   • generates output to the <ENTUITY_HOME>/etc/deviceFiles/autodisc.txt file. To specify a different name, use a parameter of -o <filename>. The device file is written in a format that can be used directly by proliferate, consisting of lines of IP addresses followed by community strings. The file also contains comments, beginning with the '#' character.
     
     
3. autoDiscovery calls proliferate, which by default adds all SNMP pollable devices to the candidate devices list in ENA.
   • If ENA recognizes the device type, they are added to the candidate devices list as devices of that type.
   • If ENA can generate an uncertified vendor file for the device type, they are added to the candidate devices list as Unclassified.
   • If ENA does not recognize the device type, they are added to the candidate devices list as devices without type.

Usage:

Usage 1:

Usage 2:

This usage is only available with SNMP v1/v2c devices.

autoDiscovery -in addresses [ -ex addresses ] [ -local ] [-follow ] [ options... ]

Search only the hosts or networks specified.

• -in <addresses>
  comma separated list of hosts or networks to include in the search.
• -ex <addresses>
  comma separated list of hosts or networks to exclude from the search.
• -local
  search the networks to which the current host is attached.
• -follow
  automatically search new network(s) that are discovered.

In this usage, autoDiscovery is run with a list of addresses to include in, or exclude from, the search.

• When you want to search the network to which the current host is attached, either include it in the list or use the -local option.
• When you want to follow new subnets, the -follow option must be given.

Usage 3:

This usage is available with SNMPv1/v2c and SNMPv3 devices.

autoDiscovery -config [ file ] [ options... ]

Read options from configuration file.

• -config
  autoDiscovery can read options and data, such as included addresses, from a configuration file. When a file is not specified, then autoDiscovery looks for the default configuration file, entuity_home/etc/autodisc.cfg.
  
  It is preferable to specify all of the required options in the configuration file, although you can also use the command line. When options have already been specified in the configuration file, the command line options usually take precedence. The exceptions are: include addresses, exclude addresses, ports and community strings where configuration file and command line values are combined.
  
  The scope of autoDiscovery's search is therefore derived from a combination of command line, configuration file and default values, e.g.:
  • if you do not include addresses, autoDiscovery takes the host's subnet as the scope. If you have included addresses but also want to search the host's subnet, then use-local. Alternatively, you can give the local network as an included address.
  • If you include addresses through the configuration file and command line, autoDiscovery will take the combined address list as its scope. If you exclude addresses through the configuration file and command line, autoDiscovery takes the combined list and excludes it from the scope.
  • if you include and exclude the same port, then autoDiscovery excludes the port from the search.
  • if you want autoDiscovery to follow subnets it discovers, then it must be configured with -follow.

Syntax options:

• -addpingonly
  Instructs autoDiscovery to set management level for the device to Ping Only when a device only responds to ping. When autoDiscovery -nodb is set, this option is ignored.
  
  
• -auto
  Instructs autoDiscovery to check the value of the automatic variable in the autodiscovery section of entuity.cfg.
  • When this value is 0, autoDiscovery is stopped and does not run automatically.
  • When this value is 1, autoDiscovery runs each Sunday at 01:00 hours.
  
  During ENA configuration, if you created your device file using autoDiscovery, then autoDiscovery will run using -auto. By default, automatic is set to 1, so autoDiscovery will automatically run every Sunday (for details on automatic see entuity.cfg).
  
  
• -c <string>
  Where <string> is a comma-separated list of community strings, with no white spaces between, to be tried when SNMP data is requested. The default, which is "public", should be included in the list if it is required. If the -c parameter is not specified, "public" is used.
  
  
• -dontallowipchange
  Instructs autoDiscovery to use the first discovered IP address on a device as its
  management address.
  
  
• -excludesysoids=<sysoid>
  Excludes the detailed sysoid from AutoDiscovery. This example excludes Cisco Unified Communications Manager from AutoDiscovery:
  -excludesysoids=1.3.6.1.4.1.311.1.1.3.1.2
  
  
• -f <n>
  This sets the SNMP final wait period, which is the period autoDiscovery waits to capture responses from final requests. When SNMP responses are slow, or you are using more threads, you may need to increase this final wait period.
  
  The SNMP final wait is linked to the ping response time (-pt). The default of 30 seconds is 10x the ping resonse time. If you amend the ping response time, you may want to maintain this 10:1 relationship.
  
  To change the final wait period, enter the new value in seconds.
  
  
• -h and -?
  Both open the help file, supplying an up-to-date list of commands and associated descriptions.
  
  
• -hn
  Do not resolve discovered IP addresses to host names. The default is on.
  
  
• -i
  Instructs autoDiscovery to mark all interfaces on discovered devices as unmanaged.
  
  
• -ith <n>
  Determines the number of addresses autoDiscovery can ping simultaneously, by setting
  the number of threads on the IP address queue. The default is 512.
  
  
• -m
  Instructs autoDiscovery to mark only management interfaces on discovered devices as
  managed.
  
  
• -ma <n>
  Sets the largest allowed subnet size that is included in the autoDiscovery search, e.g. -ma
  16 excludes from the search subnets that have more than 16 addresses. The default is
  unlimited, therefore all classes of subnets are fully pingable.
  
  
• -nodb
  Do not automatically populate the database.
  
  
• -o <filename>
  Name of device output file (default is <ENTUITY_HOME>/etc/deviceFiles/autodisc.txt).
  
  
• -p <ports>
  Where <ports> is a comma separated list of ports, with no white spaces between, to be tried when SNMP data is requested.
  
  
• -progress
  Includes progress details to standard out.
  
  
• -prune
  autoDiscovery discards networks if it receives a Network Unreachable response for the address or a subnet within it.
  
  As a prune causes autoDiscovery to discard networks, you must be careful that you specify the search address(es) at an appropriate level. If you specify a network address that has a number of subnets, it only requires one of those subnets to be unreachable for autoDiscovery to regard that whole network address being unreachable. autoDiscovery then stops searching the specified network address (possibly missing reachable subnets)
  and moves to the next specified address.
  
  For example, this network list is suitable for -prune:
  212.15.70.0
  212.15.71.0
  212.15.72.0
  204.4.143.0
  
  These are Class C subnets which do not contain subnets. If one of these networks is unreachable, it is not searched, speeding up the autoDiscovery process. The unreachable subnet does not stop autoDiscovery searching the other two subnets.
  
  In this network list the first address is not suitable for -prune:
  212.15.0.0
  204.4.143.0
  
  It is a Class B subnet which, in this example, contains subnets 212.15.70.0, 212.15.71.0, and 212.15.72.0. If a Class C subnet within the specified Class B subnet is unreachable (e.g. does not yet exist), autoDiscovery stops the discovery process on the entire Class B subnet, and if applicable searches the next specified address.
  
  Continuing the example, if 212.15.70.0 is reached, but 212.15.71.0 is unreachable, then autoDiscovery does not search for 212.15.72.0. autoDiscovery searches the next specified address, 204.4.143.0. The only data returned from 212.15.0.0 is from the first subnet, 212.15.70.0.
  
  
• -pt <n>
  Set ping timeout to n seconds. The default is 3 seconds.
  • You can decrease the timeout period to speed up autoDiscovery. On a slow network, you are increasing the probability of not including every single device.
  • You can increase the timeout period to improve the reliability of autoDiscovery results. On a slow network, this increases the length of time it takes autoDiscovery to run.
    
    
• -rememberendhosts
  Maintain a list of all IP addresses, even those that are only able to respond to ping. This is a resource-intensive setting.
  
  
• -sth <n>
  Determines the number of simultaneous autoDiscovery SNMP requests by setting the number of threads on the SNMP queue. The default is 64.
  
  
• -usestdout
  Sets autoDiscovery output to standard out (i.e. the console), rather than the output file.

To set the timeout parameter:

• The ping timeout defaults to 3 seconds. You can modify this by using the parameter -pt <n>.
• The SNMP timeout varies with the ping response time, and so you do not need to specify the SNMP timeout on the command line.
• You can speed up autoDiscovery by reducing the ping timeout. However, on a slow network this risks the possibility of not discovering every single device. You can increase confidence in the reliability of the results by increasing the ping timeout.
• You can change the final wait period by using the parameter -f <n>. This defaults to 30 to allow for worst case scenario SNMP timeout.

To set the number of threads:

You can speed up autoDiscovery by increasing the number of threads it uses, since most of the time is spent waiting for ping responses. However, more threads uses more system resources, and there is no upper limit set in autoDiscovery. This means that setting the number of threads is an advanced option.

• To set the number of threads on the IP address queue, use the parameter -ith <n>. The default is 512 threads.
• To set the number of threads on the SNMP queue, use the parameter -sth <n>. The default is 64 threads. Increasing the n argument has a less far-reaching effect than would be the case with -ith, because fewer devices get to the SNMP stage.

To write a configuration file:

Allowed section headings in a configuration file are:
[ports]
[community strings]
[included addresses]
[excluded addresses]
[options]

An example configuration file:
[ports]
161
162
[community strings]
public
[included addresses]
137.73.8.10/255.255.255.0
slinky.cs.nyu.edu
[options]
-ith=64
-sth=32
-follow
-local
-nodb

When a configuration file:

• does not contain a section of included addresses, then the subnet to which the host is currently attached is searched.
• does not contain a section of ports, then the default port 161 is used.
• does not contain a section of community strings, then the default string "public" is used.
• does not contain a particular option, then default values are used. E.g. by default, autoDiscovery does not search discovered subnets. Set the option -follow to allow autoDiscovery to search discovered subnets.

To specify an IP address:

autoDiscovery takes the IP address and subnet mask of the local machine. You can specify other machines or networks if required.

The format for specifying hosts and subnets is:

{ a[.b[.c[.d]]][/e.f.g.h] | hostname }

where each letter a..h is a number between 0 and 255 decimal inclusive.

IP addresses may be partial, and can optionally be followed by a slash and a subnet mask
on the same line. In these cases a subnet is specified. A host can also be a machine name.

Examples are:

• 204.4.143.147 (machine)
• hurricane (machine)
• 204.4.143 (subnet)
• 204.4.143.0 (subnet)
• 204.4.143.147/255.255.255.0 (subnet)

If you specify a big subnet, or if one turns up during the search, the number of potential addresses is checked against the maximum allowed. The default is not specified, so all sizes of subnets are allowed. You can change this using -ma to reduce the size of subnets that autoDiscovery is allowed to search.

Files:

For SNMPv1/v2c and SNMPv3 devices autoDiscovery configuration is defined through entuity_home/etc/autodisc.cfg. In addition, you can also configure discovery of
SNMPv1/v2c devices from the command line. Where a device supports both SNMPv1/v2c
and SNMPv3 credentials Entuity uses SNMPv3.

Discovered devices are added to Entuity and to the device file, by default <ENTUITY_HOME>/etc/deviceFiles/autodisc.txt