README for junipoll
-------------------

   intro
   -----

      junipoll - a JUNIper router snmp POLLer (for firewall filter counters).

      junipoll is an mrtg-like utility which polls the counter values
      from the firewall filters configured on Juniper routers.
      It creates ".rrd" files with names matching the router and its
      filter counter names, each containing a bytes and a pkts data
      source suitable for graphing using RRGrapher or RRDTOOL.

   prerequisites
   -------------

      - perl version 5

      - Altoids:

        http://net.doit.wisc.edu/~plonka/Altoids/

      - RRDTOOL:

        http://people.ee.ethz.ch/~oetiker/webtools/rrdtool/

      - some familiarity with MRTG and RRDTOOL

   installation
   ------------

      $ gunzip -c junipoll-1.xxx.tar.gz |tar xf -
      $ cd junipoll-1.xxx
      $ perl Makefile.PL
      $ make
      # make install

   usage
   -----

       junipoll [-v|n|V] [-m] [-c default_community] [community@]host [...]
       -v - verbose (mnemonic: 'v'erbose)
       -n - don't create or update RRD files, just show counters (implies "-v")
            (mnemonic: 'n'o, don't do anything)
       -m - name the data sources "ds0" and "ds1", rather than "pkts" and
	    "bytes", respectively, ala MRTG when "LogFormat: rrdtool" is set.
	    (mnemonic: 'm'rtg mode)
       -h - shows this usage information
            (mnemonic: 'h'elp)
       -V - show info about this junipoll version
            (mnemonic: 'V'ersion)

   The first time you run junipoll on a given router, try it out by
   using the "-n" option.  This will cause it to display the firewall
   filter counters and their values, but not create nor update the RRD
   files.  For instance:

      $ ./junipoll -n public@router
      router.jnxFWCounterPacketCount.Inbound-Filters.spoofed.2 = 106022
      router.jnxFWCounterPacketCount.Inbound-Filters.bogons-inbound.2 = 1900598
      router.jnxFWCounterPacketCount.Inbound-Filters.ms-sql-worm.2 = 45787937
      ...
      router.jnxFWCounterByteCount.Inbound-Filters.spoofed.2 = 9048609
      router.jnxFWCounterByteCount.Inbound-Filters.ms-sql-worm.2 = +18489275890
      router.jnxFWCounterByteCount.Inbound-Filters.bogons-inbound.2 = 153759455
      ...

   Once that works, you're ready to poll the counters again and record
   the initial values into RRD files:

      $ cd /path/to/dir/for/rrd/files
      $ junipoll -v public@router

   That should result in files such as the following (assuming you have
   some similarly configured firewall filters with couters):

      router_Inbound-Filters_bogons-inbound.rrd
      router_Inbound-Filters_ms-sql-worm.rrd
      router_Inbound-Filters_spoofed.rrd

   Then typically junipoll is scheduled to run every five minutes by
   configuring it in a crontab like this:

      0,5,10,15,20,25,30,35,40,45,50,55 * * * *  cd /path/to/dir/for/rrd/files >/dev/null && /usr/local/bin/junipoll public@router

   hints on use MRTG with Junipers
   -------------------------------

   Juniper router support polling of High-Capacity Interface statistics
   using SNMPv2.  One way to do this with MRTG is to specify an
   interface template when running cfgmaker.  A sample template called
   "HCInterfaceTemplate.pl", suitable for use with Juniper routers is
   suppled.

   Also, the Makefile named "mrtg_cfg.make" can be configured (see the
   "CONFIGURATION SECTION" there-in) then used thusly to produce an
   MRTG configuration file called "junipers.cfg".

      $ make -f mrtg_cfg.make

   Then MRTG can be launched as usual:

      $ mrtg junipers.cfg

--
Dave Plonka, Jun 15 2003
