Initial v1.1.0

LICENSE

@@ -1,3 +1,4 @@
+
                                  Apache License
                            Version 2.0, January 2004
                         http://www.apache.org/licenses/
@@ -178,15 +179,15 @@
    APPENDIX: How to apply the Apache License to your work.
 
       To apply the Apache License to your work, attach the following
-      boilerplate notice, with the fields enclosed by brackets "{}"
+      boilerplate notice, with the fields enclosed by brackets "[]"
       replaced with your own identifying information. (Don't include
       the brackets!)  The text should be enclosed in the appropriate
       comment syntax for the file format. We also recommend that a
       file or class name and description of purpose be included on the
       same "printed page" as the copyright notice for easier
       identification within third-party archives.
 
-   Copyright {yyyy} {name of copyright owner}
+   Copyright 2004-2017 Pascal Gloor
 
    Licensed under the Apache License, Version 2.0 (the "License");
    you may not use this file except in compliance with the License.

README.md

@@ -1,2 +1,133 @@
-# piranha
-BGP route collector written in C
+# Piranha
+A highly efficient, single threaded, BGP route collector written in C.
+Piranha collects routes and dumps them into files for further processing mainly for the purpose of analysis.
+Piranha is NOT a BGP router and does NOT have the capability to announce routes nor does it interact with the kernel routing table.
+
+Piranha supports:
+* BGP capabilities negociation.
+* BGP 4 octets ASN and AS_PATHs.
+* TCP MD5 BGP session protection.
+* IPv6 routes over IPv6 sockets.
+* IPv4 routes over IPv4 sockets.
+
+## Installation
+
+1. Download the latest version at http://xxx
+```user@piranha$ wget http://xxx```
+2. Unpack
+```user@piranha$ tar -zxvf piranha-1.1.0.tar.gz```
+3. Compilation
+```user@piranha$ [sudo] ./compile.sh <destination folder>```
+```user@piranha$ [sudo] ./compile.sh /opt/piranha/```
+*NOTE: Might need sudo if your destination is not writable by the user.*
+4. Done
+
+## Configuration
+Piranha has one configuration file located in <destination folder>/etc/piranha.conf. In the same folder there is a sample configuration name piranha_sample.conf. Copy the file to piranha.conf and edit it.
+
+### piranha.conf
+```
+# your local AS number
+local_as <ASN>
+
+# Listening IP/Port for IPv4 peers. If omitted, piranha will not listen for IPv4 connections.
+local_ip4 <local IPv4>
+local_port4 <tcp port>
+
+# Listening IP/Port for IPv6 peers. If omitted, piranha will not listen for IPv6 connections.
+local_ip6 <local IPv6>
+local_port6 <tcp port>
+
+# Export options: Choose which route attributes will be exported to the dump files
+export origin       # IGP/EGP/Unknown
+export aspath       # AS_PATH
+export community    # COMMUNITY
+export extcommunity # EXTENDED COMMUNITY
+
+# BGP Router Identifier. This MUST be set and may not be 0.0.0.0.
+# If you don't know what to put in this option, just copy your public IPv4
+# address.
+bgp_router_id <ipv4>
+
+# The user that piranha will run as. Because piranha needs
+# tcp port 179, it must be started as root. Piranha will then
+# operator a privilege downgrade to this use for obvious security
+# reasons.
+user nobody
+
+# Finally you must configure your BGP neighbors
+# You may configure up to 128 neighbors
+# (this can be changed in inc/p_defs.h:#define MAX_PEERS 128)
+# The password is optional and is implemented as defined in RFC5425
+neighbor <IPv4 or IPv6 address> <asn> [password]
+```
+## Usage
+### Start/Stop/Restart
+    <install dir>/etc/piranhactl <start|restart|stop>
+### Status (state of all neighbors)
+    cat <install dir>/var/piranha.status
+### MAN Pages
+    man -M <install dir>/man <ptoa|piranha|piranhactl|piranha.conf>
+
+## Reading Piranha DUMP
+Piranha dumps the received BGP Updates into dump files located in <install dir>/dump/<neighbor IP>. Files are rotated by default every 60 seconds. If there was no BGP message during that time, the dump not created for performance reasons. The 60 seconds interval can be tuned prior to compilation in `inc/p_defs.h:#define DUMPINTERVAL 60`.
+Dump files ready to be read have the following format: `YYYYMMddhhmmss`.
+With the tool `<install dir>/bin/ptoa` data from the dump files can be exported in three different formats:
+
+* `./ptoa -H <dump file>`: Human readable format
+* `./ptoa -m <dump file>`: Machine readable format
+* `./ptoa -j <dump file>`: JSON format
+
+### Examples
+#### Human readable format
+```
+2017-10-21 21:31:54 peer ip 2a03:2260::5 AS 201701
+2017-10-21 21:31:54 prefix announce 2a06:dac0::/29 origin IGP aspath 201701 13030 25180 202939 community 5093:5349 6629:6885 7141:7397
+2017-10-21 21:31:55 eof
+```
+#### Machine readable format
+```
+1508621514|P|2a03:2260::5|201701
+1508621514|A|2a06:dac0::|29|O|I|AP|201701 13030 25180 202939|C|5093:5349 5605:5861 6629:6885 7141:7397
+1508621515|E
+```
+#### JSON format
+```
+{ "timestamp": 1508621514, "type": "peer", "msg": { "peer": { "proto": "ipv6", "ip": "2a03:2260::5", "asn": 201701 } } }
+{ "timestamp": 1508621514, "type": "announce", "msg": { "prefix": "2a06:dac0::/29", "origin": "IGP", "aspath": [ 201701, 13030, 25180, 202939 ], "community": [ "5093:5349", "5605:5861", "6629:6885", "7141:7397" ] } }
+{ "timestamp": 1508621515, "type": "footer" }
+```
+
+### Message type tags in DUMPs
+Colons can be used to align columns.
+
+| Human | Machine | JSON | Description |
+|-|-|-|-|
+| peer | P | peer | First message in any dump describing the neighbor |
+| announce | A | announce | BGP prefix announce, optional origin (O), aspath (AP), community (C) and extended community (EC) subcomponents |
+| withdrawn | W | withdrawn | BGP prefix withdrawn |
+| eof | E | footer | Last message in any dump, has no other value |
+
+
+## Conformity
+Piranha implements partially or completely the following RFCs:
+* RFC1997: BGP Communities Attribute
+* RFC4360: BGP Extended Communities Attribute
+* RFC4760: Multiprotocol Extensions for BGP-4
+* RFC4271: A Border Gateway Protocol 4 (BGP-4)
+* RFC5425: The TCP Authentication Option
+* RFC5492: Capabilities Advertisement with BGP-4
+* RFC6793: BGP Support for Four-Octet Autonomous System (AS) Number Space
+
+## Limitations
+* Config reload does not work and may lead to a crash.
+* Extended communities are not yet supported.
+* Piranha is not able to communicate with BGP speakers not conforming to RFC5492 (old speakers).
+* Might not work on 32bits platforms (time_t handling must be improved).
+
+## Copyright
+
+*Copyright 2004-2017 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.*
+

clean.sh

@@ -0,0 +1,34 @@
+#!/bin/sh
+
+# /*******************************************************************************/
+# /*                                                                             */
+# /*  Copyright 2004-2017 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.                                             */
+# /*                                                                             */
+# /*******************************************************************************/
+
+
+
+# Piranha source cleaning script
+
+for file in bin/piranha bin/ptoa obj/*.o *.core utils/piranhactl
+do
+	if [ -r "$file" ]
+	then
+		echo "deleting $file..."
+		rm $file
+	fi
+done
+
+echo "cleaned";