summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorPavel Machek <pavel@ucw.cz>1999-12-18 21:41:19 +0100
committerPavel Machek <pavel@ucw.cz>1999-12-18 21:41:19 +0100
commitc8c0f62444a048e9d0986463ee1bfcdfc06df7c8 (patch)
tree72fe9fb36bee0057efa63d781a5e8e9d9e27cdc3
parent60d7d10e6f19483545760f2241312758dd72a2ad (diff)
downloadbird-c8c0f62444a048e9d0986463ee1bfcdfc06df7c8.tar
bird-c8c0f62444a048e9d0986463ee1bfcdfc06df7c8.zip
This is first version of documentation. Be sure to take a close look
at it, and it would be very nice if you wrote at least introductions to your chapters...
-rw-r--r--doc/bird.html200
1 files changed, 200 insertions, 0 deletions
diff --git a/doc/bird.html b/doc/bird.html
new file mode 100644
index 0000000..2401ede
--- /dev/null
+++ b/doc/bird.html
@@ -0,0 +1,200 @@
+<HTML><HEAD><TITLE>Bird</TITLE></HEAD><BODY>
+
+<!-- This is bird documentation system. It looks like html, but it is _not_ html: nonstandard
+ extensions are in use in order to auto-generate nice tex source. Use TT tag to markup short
+ texts that should be rendered in fixed-space font, and further specify what kind of text this
+ is. Currently TT file and TT conf are being used. For multi-line texts, use PRE section, again
+ with option saying what kind of section this is. Use DL conf for definition of configuration
+ keywords.
+
+ (set-fill-column 100)
+
+ Copyright 1999 Pavel Machek <pavel@ucw.cz>, distribute under GPL version 2 or later.
+
+ -->
+
+<TEX t="Insert nice, hand-generated title page here">
+
+<h1>Introduction</h1>
+
+<p>You may wonder what 'bird' means. It is acronym of 'Basic Internet Routing Daemon', and we think
+that's cool name. Its task is similar to what firmware of Cisco routers does, or what <A
+HREF="fixme">gated</A> does. However, you can not run Cisco's firmware on "normal" computer and
+gated is really hard to configure and comes under wrong license. Bird is being developed on Charles
+University, Prague, and can be freely distributed under terms of GNU General Public License. Bird is
+designed to run on unix and unix-like systems, it is primarily developed on Linux.
+
+<h2>About this documentation</h2>
+
+<p>This documentation can have 4 forms: extended html (this is master copy), html with stripped
+extensions, ascii text (generated from html) and dvi/postscript (generated from html using
+html2latex and latex). You should always edit master copy; if you do so be sure to read comment at
+beggining of file. If you want to view documentation, you can either launch your www browser at
+master copy (and hope that browser does not have incompatible extensions from our), or you can
+generate nice printed copy.
+
+<h1>Bird configuration</h1>
+
+<p>Bird is configured using text configuration file. At startup, bird reads <TT file>bird.conf</TT>
+(unless -c command line parameter is given). Really simple configuration file might look like this:
+
+<PRE conf>
+
+protocol kernel {
+ persist; # Don't remove routes on bird shutdown
+ scan time 20; # Scan kernel routing table every 20 seconds
+ export all; # Default is export none
+}
+
+protocol device {
+ scan time 10; # Scan interfaces every 10 seconds
+}
+
+protocol rip {
+ export all;
+ import all;
+}
+</PRE>
+
+<p>You can find example of more complicated configuration file in <TT file>doc/bird.conf.example</TT>.
+
+<h1>Filters</h1>
+
+<p>Bird contains rather simple programming language. (No, it can not yet read mail :-). There are
+two objects in this language: filters and functions. Filters are called by bird core when route is
+being passed between protocol and main routing table, and filters may call functions. Functions may
+call other functions but recursion is not allowed. Filter language contains control structures such
+as if's and switches, but it allows no loops. Filters are interpretted.
+
+<p pgm>You can find sources of filters language in <TT file>filter/</TT> directory. <TT
+file>filter/config.Y</TT> contains filter gramar, and basically translates source from user into
+tree of <TT c>f_inst</TT> structures. These trees are later interpreted using code in <TT
+file>filter/filter.c</TT>. Filters internally work with values/variables in <TT c>struct f_val</TT>,
+which contains type of value and value.
+
+<p>Filter basically looks like this:
+
+<PRE filt>
+filter not_too_far
+int var;
+{
+ if defined( rip_metric ) then
+ var = rip_metric;
+ else {
+ var = 1;
+ rip_metric = 1;
+ }
+ if rip_metric &gt; 10 then
+ reject "RIP metric is too big";
+ else
+ accept "ok";
+}
+</PRE>
+
+<p>As you can see, filter has a header, list of local variables, and body. Header consists of <TT
+filt>filter</TT> keyword, followed by (unique) name of filter. List of local variables consists of
+pairs <TT filt><I>type name</I>;</TT>, where each pair defines one local variable. Body consists of
+<TT filt> { <I>statments</I> }</TT>. Statements are terminated by <TT filt>;</TT>. You can group
+several statments into one by <TT filt>{ <I>statments</I> }</TT> construction, that is usefull if
+you want to make bigger block of code conditional.
+
+<h2>Variables</h2>
+
+<p>Each variable and each value has certain type. Unlike C, filters distinguish between integers and
+booleans (that is to prevent you from shooting in the foot).
+
+<DL filt>
+ <DT>bool
+ <DD>this is boolean type, it can have only two values, <TT filt>TRUE</TT> and <TT
+ filt>FALSE</TT>. Boolean is not compatible with integer and is the only type you can use
+ in if statments.
+
+ <DT>int
+ <DD>this is common integer, you can expect it to store signed values from -2000000000 to
+ +2000000000.
+
+ <DT>pair
+ <DD>this is pair of two short integers. Each component can have values from 0 to
+ 65535. Constant of this type is written as <TT filt>(1234,5678)</TT>.
+
+ <DT>string
+ <DD>this is string of characters. There are no ways to modify strings in filters. You can
+ pass them between functions, assign to variable of type string, print such variables, but
+ you can not concatenate two strings (for example). String constants are written as <TT
+ filt>"This is string constant"</TT>.
+
+ <DT>ip
+ <DD>this type can hold single ip address. Depending on version of bird you are using, it
+ can be ipv4 or ipv6 address. Ipv4 addresses addresses are written (as you would expect) as
+ <TT filt>1.2.3.4</TT>. You can apply special operator <TT filt>.mask(<I>num</I>)</TT>
+ on values of type ip. It masks out all but first <TT filt><I>num</I></TT> bits from ip
+ address. So <TT filt>1.2.3.4.mask(8) = 1.0.0.0</TT> is true.
+
+ <DT>prefix
+ <DD>this type can hold ip address, prefix len pair. Prefixes are written as <TT filt><I>ip
+ address</I>/<I>px len</I></TT>. There are two special operators on prefix: <TT
+ filt>.ip</TT>, which separates ip address from the pair, and <TT filt>.len</TT>, which
+ separates prefix len from the pair.
+
+ <DT>set int|ip|prefix|pair
+ <DD>filters know four types of sets. Sets are similar to strings: you can pass them around
+ but you can not modify them. Constant of type <TT filt>set int</TT> looks like <TT filt>
+ [ 1, 2, 5..7 ]</TT>. As you can see, both simple values and ranges are permitted in
+ sets. Sets of prefixes are special: you can specify which prefixes should match them by
+ using <TT filt>[ 1.0.0.0/8+, 2.0.0.0/8-, 3.0.0.0/8{5,6} ]</TT>.
+
+ <DT>enum
+ <DD>enumerational types are halfway-internal in the bird. You can not define your own
+ variable of enumerational type, but some pre-defined variables are of enumerational
+ type. Enumerational types are incompatible with each other, again, its for your
+ protection.
+</DL>
+
+<h1>Protocols</h1>
+
+<h2>Rip</h2>
+
+<p>Rip protocol (sometimes called Rest In Pieces) is simple protocol, where each router broadcasts
+distances to all networks he can reach. When router hears distance to other network, it increments
+it and broadcasts it back. Broadcasts are done in regular intervals. Therefore, if some network goes
+unreachable, routers keep telling each other that distance is old distance plus 1. After some time,
+distance reaches infinity (that's 15 in rip) and all routers know that network is unreachable. Rip
+tries to minimize situations where counting to infinity is neccessary, because it is slow. Due to
+infinity being 15, you can not use rip on networks where maximal distance is bigger than 15
+hosts. You can read more about rip at <A HREF="fixme">rfc1234</A>.
+
+<h3>Configuration</h3>
+
+<p>In addition to options generic to other protocols, rip supports following options:
+
+<DL conf>
+ <DT>port <I>number</I>
+ <DD>selects IP port to operate on, default 520.
+
+ <DT>authentication <I>none|password|md5</I>
+ <DD>selects authenticaion method to use. None means that packets are not authenticated at
+ all, password means that plaintext password is embedded into each packet, and md5 means
+ that packets are authenticated using md5 cryptographics hash. See <A
+ HREF="fixme">rfc1234</A>. If you set authentication to non-none, it is good idea to add
+ <TT conf>passwords { }</TT><FIXME: add reference to that section> section.
+</DL>
+
+<pre conf>
+
+protocol rip MyRIP_test {
+ debug all;
+ port 1520;
+ period 7;
+ garbagetime 60;
+ interface "*";
+ honour neighbour;
+ passwords { password "ahoj" from 0 to 10;
+ password "nazdar" from 10;
+ }
+ authentication none;
+ import filter { print "importing"; accept; };
+ export filter { print "exporting"; accept; };
+}
+</pre>
+
+</BODY></HTML>