18. External command line poller

The poller allows you to periodically scan subnets for addresses that are active on the network. This information is then logged in the IPplan database and will appear on the display subnet page. You can find the poller script in the IPplan contrib directory.

The scans are done using nmap, thus large networks can be scanned rapidly. Subnets that are to be scanned get entered into a plain text file, so maintenance is easy. Polling can be automated by adding the poller to cron.

Firstly, you will need to create a file containing a list of networks/addresses that you would like to poll. The file is a text file with one address per line in the any format that the nmap command understands (type nmap -h for more info).

10.10.10.0/24 
10.10.11.* 
10.12.12.1

Once you have created your file you will need to make sure the poller is configured correctly. Edit the poller file and change the path at the top to the correct place where the command line php can be found on your system.

You can find the location by typing

which php

Next make sure that nmap can be found. Type

which nmap

and either update the NMAP statement in the IPplan config.php file, or uncomment the NMAP define at the top of ipplan-poller.php and update to reflect the correct path to nmap. This define will override whatever is in config.php allowing a different NMAP to be used. You may also leave config.php blank to prevent scanning from within the IPplan web frontend.

Now run the ipplan-poller.php file with the -d option, or navigate to the admin->maintenance page. This will dump a list of customers and customer id's. You need to find the id of the customer you want to update:

php -q ipplan-poller.php -d

ID      Description
2       Test
46      Test customer
47      Test customer 2

Finally run the poller again with the correct command line (assuming you want to update the customer called "Test customer" which has id 46):

php -q ipplan-poller.php -c 46 -f nmap.list

If the configuration is correct and there are no errors, there should be no output - the database is updated silently in the background. Any address that was successfully polled will now have a key in the "Pol" column on the IPplan display pages.

D polled today 
W polled within last week 
M last month 
Y last year

You can now add the above line to cron to scan certain subnets periodically.

The following command line options are available with the poller:

IPplan poller v1.0

  -h        this message!
  -q        suppress check if tool is executed from the command line
  -d        dump a list of customers and customer id's
  -f        filename containing list of subnets to scan, one per line in address/bits format
                see the NMAP manpage for examples
  -hostnames    resolve and populate hostnames
  -time     timestamps the scan at start and completion
  -a        create auditlog entries for newly added records

  -c        customer id to update

  example:  php ipplan-poller.php -d
            php ipplan-poller.php -time -hostnames -f /tmp/nmap.lst -c 1

Using the -hostnames option will query the DNS when polling addresses and update the host name field within IPplan with the DNS name. Note that using this option could significantly increase polling time, especially with incorrectly configured DNS servers. Use the -time option to determine impact of using the -hostnames option.

Note

Security: You should use a different user and password to access the database using the command line poller. I suggest creating a user that can only SELECT, UPDATE and INSERT into the ipaddr table, and SELECT from the base and customer tables. See your database administrator or manual for more details.