
1. OGÓLNIE

  Braa służy do odpytywania hostów po SNMP - w odróżnieniu jednak od snmpget
z pakietu net-snmp, braa może odpytywać dziesiątki czy nawet setki i tysiące
hostów jednocześnie, i to w dodatku pracując jako jeden proces. Dzięki temu
zużywana jest niewielka ilość zasobów systemowych a samo odpytywanie (czy w
zasadzie, skanowanie) przebiega BARDZO szybko.

  Braa jest wyposażony w własny stos SNMP, nie wymaga więc żadnych bibliotek
SNMP takich jak net-snmp. Sama implementacja jest bardzo prowizoryczna,
obsługuje tylko kilka typów danych i z pewnością nie może być określona
jako 'zgodna ze standardami'. Została zaprojektowana tak aby była szybka -
i jest szybka. Z tego powodu (i oczywiście z powodu mojego lenistwa), nie
ma analizatora języka ASN.1 w braa - MUSISZ znać numeryczne wartości OID'ów
o które chcesz odpytywać. (np. .1.3.6.1.2.1.1.5.0, a nie system.sysName.0).

2. WYMAGANIA
  
  * system z rodziny *IX w którym działają gniazda BSD i kilka istotnych
    syscalli z POSIX'a
  * duża tablica ARP - jeśli chcesz odpytywać tysiące hostów, potrzebujesz
    systemu który będzie w stanie pomieścić tysiące wpisów ARP... na przykład
    zainteresuj się gc_thresh w linuksie...

  * dobrze jest mieć też zainstalowany gdzieś (niekoniecznie na tej samej
    maszynie) pełny pakiet SNMP - braa przyjmuje tylko numeryczne OIDy,
    więc czasem może się okazać, że snmptranslate to całkiem przydatne
    narzędzie...

   Braa nie do końca jest 'portable' - w każdym razie, zostało przetestowane pod
  systemami:
  
   * 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)
   * SunOS (atlantis 5.9 Generic_112233-04 sun4u sparc SUNW,Ultra-5_10)


3. INSTALACJA

  * przyjrzyj się Makefile i odkomentuj ustawienia dla Twojego systemu
  * zrób 'make'
  * skopiuj binarkę 'braa' w Twoje ulubione miejsce
   
4. UŻYCIE

  Braa potrzebuje listy zapytań, określonych w poniższej składni:
  [community@]host[:port]:oid[/id]
  Gdzie: host          to adres IP hosta z którym się połączyć
         oid           to OID o który spytać
		 port          port UDP z którym się połączyć (domyślnie: 161)
         community     to community jakim się zidentyfikować, domyślnie
                       public
		 id            identyfikator zapytania (przydatny przy używaniu
		               braa w skryptach; sam w sobie nie wpływa na proces
					   zapytania)
		 
  Przykłady:
     192.168.12.30:.1.3.6.1.2.1.1.5.0
     private@192.168.31.1:.1.3.6.1.2.1.1.6.0
  Można podać także cały zakres hostów, powiedzmy:
     10.253.100.1-10.253.105.254:.1.3.6.1.2.1.2.2.1.10.1
  to to samo co:
     10.253.100.1:.1.3.6.1.2.1.2.2.1.10.1
     10.253.100.2:.1.3.6.1.2.1.2.2.1.10.1
     10.253.100.3:.1.3.6.1.2.1.2.2.1.10.1
     ...
     ...


  Jeśli potrzebujesz odpytać hosta (lub zakres hostów) o więcej niż jedną
  wartość SNMP, musisz po prostu wpisać kilka osobnych zapytań:
     10.253.101.1-10.253.106.1:.1.3.6.1.2.1.10.127.1.1.2.1.1.4
     10.253.101.1-10.253.106.1:.1.3.6.1.2.1.2.2.1.10.1
     10.253.101.1-10.253.106.1:.1.3.6.1.2.1.2.2.1.16.1
     10.253.101.1-10.253.106.1:.1.3.6.1.2.1.10.127.1.1.1.1.6.3
     10.253.101.1-10.253.106.1:.1.3.6.1.2.1.10.127.1.2.2.1.3.2
     10.253.101.1-10.253.106.1:.1.3.6.1.2.1.10.127.1.1.4.1.5.3
  Naturalnie braa wykorzystuje możliwość wysłania kilku zapytań SNMP
  w jednym pakiecie i nigdy nie wyśle więcej niż jeden pakiet (poza
  sytuacjami retransmisji jeśli nie ma odpowiedzi) do jednego hosta -
  swoją drogą, zobacz OGRANICZENIA.

  No, tak jak zostało to wspomniane, pierwszy etap to przygotowanie listy
  zapytań. Listę można przekazać braa na dwa sposoby. Albo zapisać ją do pliku
  tekstowego, w którym jedno zapytanie == jedna linijka, albo podać serię
  opcji -q. Można także mieszać obydwie te metody, załadować kilka zestawów
  zapytań z kilku różnych plików, itd.
  
  A oto właściwa składnia:
  braa [-a] [-s N] [-r R] [-t T] [-q query [-q query [-q query ...]]] [-f file
       [-f file [-f file ...]]]
       
    WYMAGANE OPCJE:
    -q i -f   to opcje do podawania zapytań. -q pozwala na dosłowne podanie
              zapytania, -f pozwala na podanie pliku z którego zapytania
              załadować.
    OPCJE ZMIENIAJĄCE SZYBKOŚC DZIAŁANIA:
    -s N      określa ile hostów pytać w jednej turze, domyślnie 50, patrz niżej
    -r R      określa ilość retransmisji na host, domyślnie 3, patrz niżej
    -t T      określa timeout w milisekundach, patrz niżej
    OPCJE ZMIENIAJĄCE FORMAT WYJŚCIA
    -a        alternatywny format wyjścia

    Więc jak to działa?
  
    Tworzona jest kolejka N hostów i wysyłane są do niej zapytania. Braa
  czeka do 200 ms na jakieś odpowiedzi. Jeśli coś przyjdzie, hosty które
  odpowiedziały są usuwane z kolejki i kolejne hosty wchodzą w ich miejsce.
  Ilość retransmisji dla każdego hosta który nie odpowiedział jest następnie
  zwiększana - jeśli ta ilosć osiągnie R, host jest również usuwany
  z kolejki, zwalniając miejsce dla następnego. Host usunięty z kolejki
  nadal może wysłać odpowiedź i ZOSTANIE ona przyjęta, stąd opóźnienia
  pakietów są bez znaczenia, kłopot jedynie w stratach. Cały proces
  jest powtarzany dopóki nie skończą się hosty do zapełniania nowych
  miejsc w kolejce (tzn. wszyscy zostali już odpytani lub są w trakcie
  odpytywania). Kiedy tak nastąpi, kolejka jest stopniowo zmniejszana,
  i kiedy już osiągnie długość 0, braa zamyka wszystkie połączenia,
  sortuje wyniki, wyświetla je, wychodzi.
    Po T milisekundach od startu, braa pokazuje wyniki i wychodzi
  natychmiast, niezależnie od tego ile hostów zostało już odpytanych,
  a do ilu nie poszło nawet pół pakietu...

    Jak widać, algorytm nie jest doskonały. Jak wspomniałem, chodziło o to,
  żeby był jak najszybszy. Domyślne wartości dla -s i -r są całkiem w porządku,
  ale oczywiście zawsze możesz je 'podkręcić' tak, aby braa chodziło jeszcze
  szybciej (ale mniej dokładnie). Jeśli odpytujesz bardzo dużą ilość hostów, nie
  zapomnij zwiększyć znacząco -t.

    Wyniki są wypisywane na stdout, jeden-na-linię:  
    192.168.1.2:.1.3.6.1.2.1.1.5.0:do-wan.elsat.net.pl
    192.168.1.1:.1.3.6.1.2.1.1.4.0:"Mateusz Golicz MG452-RIPE <mtg@elsat.net.pl>"
    192.168.1.1:.1.3.6.1.2.1.1.5.0:ergsun

    Lub jeśli podasz -a, host-na-linię z wynikami oddzielonymi spacją, w kolejności
  w której zostały podane zapytania o nie:

    10.253.105.245 358 410 -137 276783656 16315982 4
    10.253.105.244 387 480 -105 6611527 391938 1
    10.253.105.242 371 282 182 0 0 2
    10.253.105.239 373 430 34 0 0 6
    10.253.105.238 354 510 -163 262523537 12319047 4
    
	Przy standardowym trybie wypisywania wyników braa może przed każdym rezultatem
  zapytania wypisać jego podany przez użytkownika identyfikator; ta opcja może
  być przydatna do przetwarzania wyjścia z braa w skryptach. Przykładowo, zapytanie o:
    192.168.1.2:.1.3.6.1.2.1.1.5.0/Test
    zwróci coś w rodzaju:
	Test/192.168.1.2:.1.3.6.1.2.1.1.5.0:do-wan.elsat.net.pl
    
5. PRZYKŁADY

    braa -f queries.lst \
         -q 192.168.1.1:.1.3.6.1.2.1.1.5.0 \
         -q 192.168.1.1:.1.3.6.1.2.1.1.4.0 \
         -q 192.168.1.2:.1.3.6.1.2.1.1.4.0
    
    braa -s 50 -ar 3 -t 250000 -q 10.253.101.1-10.253.106.1:.1.3.6.1.2.1.10.127.1.1.2.1.1.4 \
                               -q 10.253.101.1-10.253.106.1:.1.3.6.1.2.1.2.2.1.10.1 \
                               -q 10.253.101.1-10.253.106.1:.1.3.6.1.2.1.2.2.1.16.1 \
                               -q 10.253.101.1-10.253.106.1:.1.3.6.1.2.1.10.127.1.1.1.1.6.3 \
                               -q 10.253.101.1-10.253.106.1:.1.3.6.1.2.1.10.127.1.2.2.1.3.2 \
                               -q 10.253.101.1-10.253.106.1:.1.3.6.1.2.1.10.127.1.1.4.1.5.3

5. BŁEDY I OGRANICZENIA

  * jedynymi obsługiwanymi typami danych są: integer (gauge, counter, timeticks,
    etc.), string and OID. Oczywiście zawsze możesz poprawić braaasn.c/braaasn.h.
  * braa nigdy nie wyśle więcej niż 1500 bajtów (lub pojedynczy pakiet) do hosta
    w pojedynczej próbie. Stąd ilość zapytań jakie możesz zadać jednemu hostowi
    jest ograniczona. Dodatkowo, kiedy osiągniesz ten limit podając zbyt
    wiele zapytań, braa przerwie cały proces skanowania. Nie potrafię określić
    ile dokładnie wynosi ten limit, po prostu zależy to od wielu czynnmików
    (głównie, długości OID'ów), w każdym razie, 15 zapytań na hosta brzmi
    dość niebezpiecznie i lepiej nie przekraczaj tej liczby.
  * nie da się używać nazw domenowych hostów - zawsze musisz podawać IP.
    cóż, to drobiazg, myślę że w następnej wersji (o ile będzie) zostanie
    to poprawione. 
  * braa prawdopodobnie nie ruszy w środowiskach 64-bitowych

6. AUTORZY, PODZIEKOWANIA

  Mateusz 'mteg' Golicz <mtg@elsat.net.pl>

7. LICENCJA

  Pakiet rozpowszechniany jest na zasadach licencji GNU GPL, wersja 2.

Mateusz 'mteg' Golicz <mtg@elsat.net.pl>
