

   //--==========================================================--\\ 
   ||           ____  _                 _                          ||
   ||          |  _ \(_)_ __ __ _ _ __ | |__   __ _                ||
   ||          | |_) | | '__/ _` | '_ \| '_ \ / _` |               ||
   ||          |  __/| | | | (_| | | | | | | | (_| |               ||
   ||          |_|   |_|_|  \__,_|_| |_|_| |_|\__,_|               ||
   ||                                                              ||
   ||                                                              ||
   ||  Version : 0.99.0                                            ||
   ||  Author  : Pascal Gloor [spale]                              ||
   ||  Changed : 6 Aug 2004                                        ||
   ||                                                              ||
   \\--==========================================================--//


   INDEX
   =====

   1. WHAT IS PIRANHA ?

   2. INSTALLATION

   3. CONFIGURATION

      3.1 PIRANHA
      3.2 CISCO (IOS)
      3.3 JUNIPER (JUNOS)

   4. RUNNING / FILES

   5. DUMPS FORMAT

   6. BUGS

   7. AUTHOR(S) / CREDITS

   8. LICENSE

   NOTE: Please apologize my poor english, comments/corrections
          are welcome in the hope of removing this note ;)

   NOTE: We assume here that you know what BGP is and how it works.

   NOTE: In all the examples below, we assume that the installtion
         directory is /usr/local/piranha.


   /-==============================================================-\ 
   | 1.    WHAT IS PIRANHA ?                                        |
   \-==============================================================-/

   Piranha is a BGP daemon. Unlike other known BGP daemons (OpenBSD
   BGPD, Zebra, Quagga, etc...) it is not a router. Piranha is a BGP
   collector, and does only that. it has been done for that and so
   is performant in this.


   /-==============================================================-\ 
   | 2.    INSTALLATION                                             |
   \-==============================================================-/

   Piranha is known to run well on the following operating systems
   and compilers :

      GCC 3.x / 2.95.x

         FreeBSD 4.x,5.x
         Linux 2.2.x/2.4.x
         Darwin 7.x (MacOS X 10.3.x)

   NOTE: The system *must* be POSIX threads capable, this IS mandatory.

   To install Piranha simply run the compile/install script located
   at the root of the package.

      ./compile.sh <destination directory> [debug]

      destination directory : something like /usr/local/piranha
      debug                 : is optional, will compile Piranha
                              with all debugging options.

   /-==============================================================-\ 
   | 3.    CONFIGURATION                                            |
   |-==============================================================-|
   | 3.1   PIRANHA                                                  |
   \-==============================================================-/

   After installing Piranha you will have a sample configuration
   located at:

      /usr/local/piranha/etc/sample_piranha.conf

   The format of the configuration file is as following:

      <directive> <value 1> [value 2] [value n] ...

   Mandatory directives:

      local_ip <ip address in dotted format xxx.xxx.xxx.xxx>

         local ip address on which the socket will be binded to.
         it will also be used as the 'router-id' and therefor you
         can NOT use 0.0.0.0 !!!

      local_as <autonomous system number>

         local AS number.

   Optional directives:

      bgp_holdtime <seconds>

         holdtime in seconds of the BGP sessions. You *should* NOT
         use 0 (even if RFC1771 allows it). it is known that certain
         BGP implementations do not support a holdtime of 0.
         bgp_holdtime defaults to 180 seconds.

      local_port <tcp port number>

         local port number, defaults to 179 (BGP).

   BGP Neighbors directives:

      neighbor <ip address> <autonomous system number>

         defines a neighbor/peer with its ip address and ASN. the ip
         address and the ASN *must* match, otherwise the peer will be
         rejected.

   /-==============================================================-\ 
   | 3.2    CISCO (IOS)                                             |
   \-==============================================================-/

   Here is a little sample configuration for your cisco to connect
   to the Piranha.

      !
      router bgp <your ASN>
       ...
       neighbor <piranha's IP> remote-as <piranha's ASN>
       neighbor <piranha's IP> update-source <interface>
       neighbor <piranha's IP> ebgp-multihop <max hops>
       ...
     !

   /-==============================================================-\ 
   | 3.3   JUNIPER (JUNOS)                                          |
   \-==============================================================-/

   to be done...

   /-==============================================================-\ 
   | 4.    RUNNING / FILES                                          |
   \-==============================================================-/

   to run Piranha:

      /usr/local/piranha/bin/piranha /usr/local/piranha/etc/piranha.conf

      kill -HUP `cat /usr/local/piranha/var/piranha.pid`
      (will reload the configuration file)

   Piranha's status: /usr/local/piranha/var/piranha.status

   sample output:

      /---------------------------------------------------------\
      | neighbor          asn    recv    sent status    up/down |
      |---------------------------------------------------------|
      | 192.168.1.1     65500   21647       4 up          0m22s |
      | 192.168.1.22    65501       0       0 down        1m19s |
      \---------------------------------------------------------/

   Piranha's log file /usr/local/piranha/var/piranha.log

   sample output:

      [2004-07-29 21:55:57] Piranha v0.99.0 started.
      [2004-07-29 21:57:08] 192.168.1.1 connection (known)
      [2004-07-29 21:57:08] 192.168.1.1 established

   Piranha's PID file /usr/local/piranha/var/piranha.pid

   Piranha's BGP update dumps are located in:
      /usr/local/piranha/dump/<neighbor ip address>/<YYYYmmddHHMMSS>

   /-==============================================================-\ 
   | 5.    DUMPS FORMAT                                             |
   \-==============================================================-/

   The format of the dump files have been designed to be forward and
   backward compatible. Indeed you MUST follow the format described
   below.

   NOTE: dump files will ALWAYS use the network byte order to be
         platform independant (htons/htonl are your friends on
         x86(Intel) architecture).


   The dump file is composed of multiple records.

   RECORD (the header for every message)

   0                   1                   2                   3
   0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |          message code         |          message length       |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |                        event timestamp                        |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |  message data (variable) ...
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-...

      MESSAGE CODE (2 octets)

         0   HEADER    (MUST be present at the begining of each file)
         1   BGP_OPEN  (when a bgp session becomes established)
         2   BGP_CLOSE (when a bgp session is dropped)
         3   KEEPALIVE (when a BGP keepalive is received)
         4   ANNOUNCE  (when a new BGP prefix is announced)
         5   WITHDRAWN (when a BGP prefix is withdrawn)
       255   FOOTER    (MUST be present at the end of each file)

      MESSAGE LENGTH (2 octets)

         The length of the data part in number of bytes.

      EVENT TIMESTAMP (4 octets)

         timestamp of the record in unixtime.

      MESSAGE DATA (variable length, defined by MESSAGE LENGTH)

         HEADER (code 0)

            no defined data (0 octets)

         BGP_OPEN (code 1)

   0                   1                   2                   3
   0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |                   neighbor ip address                         |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   | neighbor autonomus system     |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

            the neighbor ip address (4 octets) followed by it's
            autonomus system number/ASN (2 octets).

         BGP_CLOSE (code 2)

            no defined data (0 octets)

         KEEPALIVE (code 3)

            no defined data (0 octets)

         ANNOUNCE (code 4)

            starts with the prefix length (also known as the bit-mask),
            followed by the prefix itself (4 octets).

            note: the prefix failing bits, MUST be ignored and assumed
                  to be set to 0.

            the rest of the message is composed of triplets for options.


   0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+...
   |   option code |            option len         | option data (variable)
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+...

                ASPATH    (code 1)
                COMMUNITY (code 2)

		unknown option code MUST be ignored.

         WITHDRAWN (code 5)

            starts with the prefix length (also known as the bit-mask),
            followed by the prefix itself (4 octets).

            note: the prefix failing bits, MUST be ignored and assumed
                  to be set to 0.

            
     NOTE: Unknown options MUST be ignored to assure compatibility!


   /-==============================================================-\ 
   | 6.    BUGS                                                     |
   \-==============================================================-/

   Bug reports (and their possible fix/patch) have to be sent with
   complete explanation (platform/os/configuration/etc..) to:

   <piranha_bugs@spale.com>

   /-==============================================================-\ 
   | 7.    AUTHOR(S) / CREDITS                                      |
   \-==============================================================-/

   Pascal Gloor aka [spale] <pascal.gloor@spale.com>  Author

   The NETLANTIS Project, home of the Piranha project ;)
   (know netlantis? the place 'where all the routes meet...')


   Many thanks to the people who supported me in this project:

       Philippe Bourcier aka Mr_RIP
       Stephane Thiell aka mbuna
       Perry Lorier aka Isomer
       Tamama
       Braden,
       and many more...

   /-==============================================================-\ 
   | 8.    LICENSE                                                  |
   \-==============================================================-/

    Copyright 2004 Pascal Gloor

    Licensed under the Apache License, Version 2.0 (the "License");
    you may not use this file except in compliance with the License.
    You may obtain a copy of the License at

       http://www.apache.org/licenses/LICENSE-2.0

    Unless required by applicable law or agreed to in writing, software
    distributed under the License is distributed on an "AS IS" BASIS,
    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    See the License for the specific language governing permissions and
    limitations under the License.


End-of-Document
