//--==========================================================--\\ || ____ _ _ || || | _ \(_)_ __ __ _ _ __ | |__ __ _ || || | |_) | | '__/ _` | '_ \| '_ \ / _` | || || | __/| | | | (_| | | | | | | | (_| | || || |_| |_|_| \__,_|_| |_|_| |_|\__,_| || || || || || || 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 [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: [value 2] [value n] ... Mandatory directives: local_ip 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 local AS number. Optional directives: bgp_holdtime 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 local port number, defaults to 179 (BGP). BGP Neighbors directives: neighbor 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 ... neighbor remote-as neighbor update-source neighbor ebgp-multihop ... ! /-==============================================================-\ | 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// /-==============================================================-\ | 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: /-==============================================================-\ | 7. AUTHOR(S) / CREDITS | \-==============================================================-/ Pascal Gloor aka [spale] 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