1. OVERVIEW

  Braa is a mass snmp scanner. The intended usage of such a tool is of course 
making SNMP queries - but unlike snmpget or snmpwalk from net-snmp, it is able
to query dozens or hundreds of hosts simultaneously, and in a single process.
Thus, it consumes very few system resources and does the scanning VERY fast.
  
  Braa implements its OWN snmp stack, so it does NOT need any SNMP libraries
like net-snmp. The implementation is very dirty, supports only several data
types, and in any case cannot be stated 'standard-conforming'! It was designed
to be fast, and it is fast. For this reason (well, and also because of my
laziness ;), there is no ASN.1 parser in braa - you HAVE to know the numerical
values of OID's (for instance .1.3.6.1.2.1.1.5.0 instead of system.sysName.0).

2. REQUIREMENTS
  
  * an *IX system implementing BSD sockets and some POSIX syscalls
  * large ARP table - if you plan to query thousands of hosts, make
    sure your system is capable of managing thousands of ARP entries,
    for instance tune the gc_thresh values in Linux...

  * it is also good to have a complete SNMP package installed somewhere,
    because braa accepts only numerical OID's, so you may need to make
    use of snmptranslate.

  Braa is not at all portable - it was tested only on several setups:
  * Linux (shaerrawedd 2.4.19-xfs #7 Fri Oct 4 18:18:38 CEST 2002 i686 unknown)
  * FreeBSD (venom 4.6.2-RELEASE-p10 FreeBSD 4.6.2-RELEASE-p10 #0: Tue Mar 25
           12:59:45 CET 2003     root@venom:/usr/src/sys/compile/VENOM-3  i386)
  * OpenBSD (pantera 3.3 PANTERA#0 i386)

  With minor adjustments, braa should also work under SunOS, and actually, any
  POSIX-compilant UNIX system. The problem is I just do not have access to any
  machines running something different than BSD or Linux.

3. INSTALLATION

  * edit Makefile and uncomment the right setting for your OS
  * do a 'make'
  * copy the 'braa' binary into a desired place.
   
4. USAGE

    Braa is controlled from the command line using a standard
  getopt approach:
  
  braa [-2] [-v] [-t <s>] [-f <file>] [-a <time>] [-r <retries>] [-d <delay>] [querylist1] [querylist2] ...

    As you can see, the list of queries to make is specified as a
  commandline argument. The syntax of the query list follows:
  
    [community@]host1[-host2][:port]:query1[/id][,query2[/id][,query3[/id]...]]

    Well, this seems quite complicated, but let us have a look at few examples:
	
	10.253.101.1:.1.3.6.1.2.1.1.6.0
	10.253.101.1:.1.3.6.1.2.1.1.*
	10.253.101.1-10.253.101.50:.1.3.6.1.2.1.1.6.0
	10.253.101.1:.1.3.6.1.2.1.1.4.0/ContactPerson,.1.3.6.1.2.1.4.20.*/RoutingTable
	[email protected]:.1.3.6.1.2.1.1.6.0=sMy network
	
	The strings after the last colon are the actual queries to be made. To make
  a GET query (to retrieve a value under a specific Object ID, just what snmpget
  does), one specifies only the Object ID. As it was stated in the Overview,
  braa accepts only numerical OIDs, and this is why you need the fully-featured
  SNMP package: to translate OIDs. You can get numerical OIDs from symbolic ones
  using the 'snmptranslate' command from a complete SNMP package, usually by
  issuing something like:

    $ snmptranslate -mall system.sysLocation.0
    .1.3.6.1.2.1.1.6.0

    So, the first example is a GET query on object .1.3.6.1.2.1.1.6.0 - which is
  just system.sysLocation.0. Running 'braa 10.253.101.1:.1.3.6.1.2.1.1.6.0'
  would return something like:
  
    10.253.101.1:25ms:.1.3.6.1.2.1.1.6.0:Elsat HFC Network, Ruda Sl/Bytom/Radzionkow, Poland

    Which means 10.253.101.1 answered in about 25 ms and claimed, that
  system.sysLocation.0 contains the string "Elsat HFC (...)". Keep on mind
  that the response time is in fact very inaccurate...


    Another query type is the WALK query. WALK queries make braa traverse
  the object tree hierachy ,,below'' a specified object, like snmpwalk
  does. The second example:
	10.253.101.1:.1.3.6.1.2.1.1.*
    is a WALK query on the 'system' (.1.3.6.1.2.1.1) object; the output
  would look like:

    10.253.101.1:26ms:.1.3.6.1.2.1.1.1.0:Thomson DOCSIS Cable Modem <<HW_REV: 2.1; VENDOR: Thomson; BOOTR: 2.1.4c; SW_REV: ST33.02.04; MODEL: TCM390>>
    10.253.101.1:24ms:.1.3.6.1.2.1.1.2.0:.1.3.6.1.4.1.2863.390.2.1.51.2.4
    10.253.101.1:28ms:.1.3.6.1.2.1.1.3.0:726500
    10.253.101.1:28ms:.1.3.6.1.2.1.1.4.0:Mateusz Golicz MG452-RIPE <[email protected]>
    10.253.101.1:27ms:.1.3.6.1.2.1.1.5.0:Thomson 390 DOCSIS CM, DOCSIS 1.1 MODE
    10.253.101.1:27ms:.1.3.6.1.2.1.1.6.0:Elsat HFC Network, Ruda Sl/Bytom/Radzionkow, Poland
    ...
    
	To query 50 hosts, from 10.253.101.1 to 10.253.101.50 for
  system.sysLocation.0 one could of course issue something like:

    braa 10.253.101.1:.1.3.6.1.2.1.1.6.0 10.253.101.2:.1.3.6.1.2.1.1.6.0 ...

    ... but it is much more comfortable to specify a host range instead a single
  host in the query list specification, like in the third example:

    braa 10.253.101.1-10.253.101.50:.1.3.6.1.2.1.1.6.0
  
    And as usually, the output: 
	
	10.253.101.47:53ms:.1.3.6.1.2.1.1.6.0:Elsat HFC Network, Ruda Sl/Bytom/Radzionkow, Poland
    10.253.101.46:55ms:.1.3.6.1.2.1.1.6.0:Elsat HFC Network, Ruda Sl/Bytom/Radzionkow, Poland
    10.253.101.1:56ms:.1.3.6.1.2.1.1.6.0:Elsat HFC Network, Ruda Sl/Bytom/Radzionkow, Poland
    10.253.101.42:84ms:.1.3.6.1.2.1.1.6.0:Elsat HFC Network, Ruda Sl/Bytom/Radzionkow, Poland


    As you can see in the next example:

    10.253.101.1:.1.3.6.1.2.1.1.4.0/ContactPerson,.1.3.6.1.2.1.4.20.*/RoutingTable

    ... a comma character is used to separate queries in case one wants to
  specify more queries in a query list. The example also shows how to make
  advantage of query IDs. The IDs (after a slash) do not affect the querying
  process itself, but they are just printed before appropiate lines of output:
  
    ContactPerson:10.253.101.1:25ms:.1.3.6.1.2.1.1.4.0:Mateusz Golicz MG452-RIPE <[email protected]>
    RoutingTable:10.253.101.1:29ms:.1.3.6.1.2.1.4.20.1.1.10.253.101.1:10.253.101.1
    RoutingTable:10.253.101.1:23ms:.1.3.6.1.2.1.4.20.1.1.127.0.0.1:127.0.0.1
    RoutingTable:10.253.101.1:26ms:.1.3.6.1.2.1.4.20.1.1.192.168.100.1:192.168.100.1
    RoutingTable:10.253.101.1:27ms:.1.3.6.1.2.1.4.20.1.2.10.253.101.1:2

    ... so it is easier to split and parse braa output using automated
  tools like awk.


    The last example demonstrates the SET query: 

	[email protected]:.1.3.6.1.2.1.1.6.0=sMy network
	
	This attempts to set .1.3.6.1.2.1.1.6.0 (which is again my
  favourite system.sysLocation.0) at hosts 10.253.101.1 up to 50 to
  'My network'. The "s" before the right value specifies the value type;
  braa supports currently:
     s String      (eg. "sMy Network")
	 a IP Address  (eg. "a10.253.100.1")
	 i Integer     (eg. "i10")
	 o OID         (eg. "o.1.3.6.1.2.1.4.20.1.1.10.253.101.1")
	If the type prefix is not specified (eg. the character after
  '=' is none of the above), braa attempts to auto-detect the type.

	The 'private@' part before the host range of course sets the
  SNMP community name for the transaction to 'private'.

    ... and that seems to be all about the query format. You may
  also make a file containing the query lists one by line instead
  of providing them as commandline arguments. Use the -f option to
  load queries from such a list. Other options are:

    -r <count>     retry count: try making each query <count> times 
  before giving up. By default, the retry count is set to 3.
  
    -a <seconds>   deadline time; makes braa quit after <seconds> 
  seconds, independent on what happens. 

    -2             SNMPv2C - braa will introduce itself as a SNMPv2C
  agent (but in fact the packets are always constructed according
  to SNMP1 RFCs). This is useful for retrieving data from objects
  that hold data types not covered by the SNMP1 specification - at
  the moment the only such supported data type is Counter64.
  
    -t <seconds>   Wait <seconds> seconds for responses. When
  nothing happens for the given time (there are no more messages
  to send and nothing more is received), braa quits. The default
  is 2 seconds.
  
    -d <micro>     Makes braa wait for <micro> microseconds after
  sending each packet. Useful if the bandwidth between you and
  the devices you are querying is limited - see the short explanation
  on how braa works below.
  
    -h             Help, shows a short summary of this manual ;)

5. REMARKS

    Braa takes full advantage of the possibility to make serveral SNMP
  queries using a single SNMP packet and will never send more than one
  packet per a query type (of course except retries if there was no answer)
  to a host (btw, see LIMITATIONS). This means that the following commands:
  
     braa 10.253.101.1:.1.3.6.1.2.1.1.6.0 10.253.101.1:.1.3.6.1.2.1.1.5.0
     braa 10.253.101.1:.1.3.6.1.2.1.1.5.0,.1.3.6.1.2.1.1.6.0

    Do EXACTLY the same: a SINGLE packet requesting information on
  .1.3.6.1.2.1.1.5.0 and .1.3.6.1.2.1.1.6.0 is sent to 10.253.101.1.
  
    Braa sends queries for every host on the query list, meanwhile
  listening for answers (non-blocking sockets are used for this
  purpose). Every upcoming answer is immediately decoded and
  outputted. After queries for all hosts have been sent, it waits
  20 ms, and then every host that did not answered in the first pass is
  sent the query again. The passes continue, until the retry count
  (specified using the -r option) is achieved or until all the hosts
  have answered. In the first case, braa waits then for any delayed
  messages for 2 seconds (this timeout might be changed by the -t option).

    Each time a packet is sent, braa might wait for a short period so
  as not to flood the link to its SNMP peers. This is controlled by the
  -d option.
  
    When querying multiple hosts always make sure your ARP table
  can hold enough entries (eg. you might have to adjust
  /proc/sys/net/ipv4/neigh/default/gc_thresh* under Linux).

6. BUGS AND LIMITATIONS

  * the only supported datatypes are: integer (gauge, counter, timeticks, etc.)
    counter64, string, ipaddress, OID. Of course you are free to modify
	braaasn.c/braaasn.h to support more types...
  * braa will never send more than 1500 bytes (or a single packet) to a host
    in a single try. Thus the number of queries that might be sent to a single
    host is limited. Additionally, if you reach the limit by specifying too many
    queries, braa will terminate the whole scanning process... I can't tell
    what the limit exactly is, it just depends on many factors (mainly, the
    length of OIDs), anyway, 15 queries per hosts sounds dangerous, and better
    try not to exceed this number.
  * it is impossible to specify FQDN hostnames - you always have to give IP
    addresses of hosts... well, I think it'll be corrected in future
    versions, if there will be ones.

7. AUTHORS, ACKNOWLEDGEMENTS

  Mateusz 'mteg' Golicz <[email protected]>

8. LICENSE

  The package is licensed on GNU General Public License. See COPYING file.

Mateusz 'mteg' Golicz <[email protected]>