Revision 371adba6

View differences:

doc/bird.sgml
13 13

  
14 14
 -->
15 15

  
16
<article>
16
<book>
17 17

  
18 18
<title>BIRD User's Guide
19 19
<author>
......
31 31

  
32 32
<!-- Begin the document -->
33 33

  
34
<sect>Introduction
34
<chapt>Introduction
35 35

  
36
<sect1>What is BIRD
36
<sect>What is BIRD
37 37

  
38 38
<p><label id="intro">
39 39
The name `BIRD' is actually an acronym standing for `BIRD Internet Routing Daemon'.
......
94 94
tested under Linux 2.0 to 2.3, but porting to other systems (even non-UNIX ones) should
95 95
be relatively easy due to its highly modular architecture.
96 96

  
97
<sect1>About this documentation
97
<sect>About this documentation
98 98

  
99 99
<p>This documentation can have 4 forms: sgml (this is master copy), html, ASCII text and dvi/postscript (generated from sgml using sgmltools). You should always edit master copy.
100 100

  
101
<sect1>About routing tables
101
<sect>About routing tables
102 102

  
103 103
<p>Bird has one or more routing tables, which may or may not be
104 104
synchronized with kernel and which may or may not be synchronized with
......
127 127
filters. Filters can alter routes passed between routing tables and
128 128
protocols.
129 129

  
130
<sect1>Installing BIRD
130
<sect>Installing BIRD
131 131

  
132 132
<p>On recent UNIX (with GNU-compatible tools -- BIRD relies on GCC extensions)
133 133
system, installing BIRD should be as easy as:
......
160 160
	use given filename for socket for communications with bird client, default is <file/bird.ctl/.
161 161
</descrip>
162 162

  
163
<sect>Configuration
163
<chapt>Configuration
164 164

  
165
<sect1>Introduction
165
<sect>Introduction
166 166

  
167 167
<p>BIRD is configured using text configuration file. At startup, BIRD reads <file/bird.conf/ (unless
168 168
<tt/-c/ command line option is given). Configuration may be changed on user request: if you modify
......
200 200
</code>
201 201

  
202 202

  
203
<sect1>Global options
203
<sect>Global options
204 204

  
205 205
<p><descrip>
206 206
	<tag>log "<m/filename/"|syslog|stderr all|{ <m/list of classes/ }</tag> 
......
244 244
	is used by us for testing.
245 245
</descrip>
246 246

  
247
<sect1>Protocol options
247
<sect>Protocol options
248 248

  
249 249
<p>Several options are per-protocol, but all protocols support them. They are described here.
250 250

  
......
286 286
						  
287 287
</descrip>
288 288

  
289
<sect1>Client
289
<sect>Client
290 290

  
291 291
<p>You can use command-line client <file>birdc</file> to talk with
292 292
running BIRD. Communications is done using <file/bird.ctl/ unix domain
......
301 301
BIRD and BIRDC is stable (see programmer's documentation).
302 302

  
303 303

  
304
<sect>Filters
304
<chapt>Filters
305 305

  
306
<sect1>Introduction
306
<sect>Introduction
307 307

  
308 308
<p>BIRD contains rather simple programming language. (No, it can not yet read mail :-). There are
309 309
two objects in this language: filters and functions. Filters are called by BIRD core when route is
......
390 390
bird>
391 391
</code>
392 392

  
393
<sect1>Data types
393
<sect>Data types
394 394

  
395 395
<p>Each variable and each value has certain type. Unlike C, booleans, integers and enums are
396 396
incompatible with each other (that is to prevent you from shooting in the foot).
......
462 462

  
463 463
</descrip>
464 464

  
465
<sect1>Operations
465
<sect>Operations
466 466

  
467 467
<p>Filter language supports common integer operations <cf>(+,-,*,/)</cf>, parentheses <cf/(a*(b+c))/, comparison
468 468
<cf/(a=b, a!=b, a&lt;b, a&gt;=b)/. Special operators include <cf/&tilde;/ for "in" operation. In operation can be
......
471 471
is true if element is in given set or if ip address is inside given prefix. Operator <cf/=/ is used to assign value
472 472
to variable. Logical operations include unary not (<cf/!/), and (<cf/&&/) and or (<cf/||/>).
473 473

  
474
<sect1>Control structures
474
<sect>Control structures
475 475

  
476 476
<p>Filters support two control structures: if/then/else and case. Syntax of if/then/else is <cf>if
477 477
<M>expression</M> then <M>command</M>; else <M>command</M>;</cf> and you can use <cf>{
......
498 498
if 1234 = i then printn "."; else { print "not 1234"; print "You need {} around multiple commands"; }
499 499
</code>
500 500

  
501
<sect1>Route attributes
501
<sect>Route attributes
502 502

  
503 503
<p>Filter is implicitly passed route, and it can access its
504 504
attributes, just like it accesses variables. Access to undefined
......
533 533

  
534 534
<p>Plus, there are protocol-specific attributes, which are described in protocol sections.
535 535

  
536
<sect1>Utility functions
536
<sect>Utility functions
537 537

  
538 538
<p>There are few functions you might find convenient to use:
539 539

  
......
552 552
	terminates bird. Useful while debugging filter interpreter.
553 553
</descrip>
554 554

  
555
<sect>Protocols
555
<chapt>Protocols
556 556

  
557
<sect1>BGP
557
<sect>BGP
558 558

  
559 559
<p>The Border Gateway Protocol is the routing protocol used for backbone
560 560
level routing in the today's Internet. Contrary to other protocols, its convergence
......
590 590
and applied to IPv6 according to
591 591
RFC 2545<htmlurl url="ftp://ftp.rfc-editor.org/in-notes/rfc2545.txt">.
592 592

  
593
<sect2>Route selection rules
593
<sect1>Route selection rules
594 594

  
595 595
<p>BGP doesn't have any simple metric, so the rules for selection of an optimal
596 596
route among multiple BGP routes with the same preference are a bit more complex
......
608 608
	advertising router.
609 609
</itemize>
610 610

  
611
<sect2>Configuration
611
<sect1>Configuration
612 612

  
613 613
<p>Each instance of the BGP corresponds to one neighboring router.
614 614
This allows to set routing policy and all other parameters differently
......
670 670
	is missing. Default: 0.
671 671
</descrip>
672 672

  
673
<sect2>Attributes
673
<sect1>Attributes
674 674

  
675 675
<p>BGP defines several route attributes. Some of them (those marked with `I' in the
676 676
table below) are available on internal BGP connections only, some of them (marked
......
715 715
	attributes it defines and what their semantics will be.
716 716
</descrip>
717 717

  
718
<sect2>Example
718
<sect1>Example
719 719

  
720 720
<p><code>
721 721
protocol bgp {
......
736 736
}
737 737
</code>
738 738

  
739
<sect1>Device
739
<sect>Device
740 740

  
741 741
<p>The Device protocol is not a real routing protocol as it doesn't generate
742 742
any routes and only serves as a module for getting information about network
......
765 765
}
766 766
</code>
767 767

  
768
<sect1>Direct
768
<sect>Direct
769 769

  
770 770
<p>The Direct protocol is a simple generator of device routes for all the
771 771
directly connected networks according to the list of interfaces provided
......
797 797
}
798 798
</code>
799 799

  
800
<sect1>Kernel
800
<sect>Kernel
801 801

  
802 802
<p>The Kernel protocol is not a real routing protocol. Instead of communicating
803 803
with other routers in the network, it performs synchronization of BIRD's routing
......
814 814
them must be connected to a different BIRD routing table and to a different
815 815
kernel table.
816 816

  
817
<sect2>Configuration
817
<sect1>Configuration
818 818

  
819 819
<p><descrip>
820 820
	<tag>persist <m/switch/</tag> Tell BIRD to leave all its routes in the
......
859 859

  
860 860
<p>The Kernel protocol doesn't define any route attributes.
861 861

  
862
<sect1>OSPF
862
<sect>OSPF
863 863

  
864
<sect1>Pipe
864
<sect>Pipe
865 865

  
866
<sect2>Introduction
866
<sect1>Introduction
867 867

  
868 868
<p>The Pipe protocol serves as a link between two routing tables, allowing routes to be
869 869
passed from a table declared as primary (i.e., the one the pipe is connected using the
......
883 883
and also you can employ the Pipe protocol to export a selected subset of one table in
884 884
another one.
885 885

  
886
<sect2>Configuration
886
<sect1>Configuration
887 887

  
888 888
<p><descrip>
889 889
	<tag>peer table <m/table/</tag> Define secondary routing table to connect to. The
890 890
	primary one is selected by the <cf/table/ keyword.
891 891
</descrip>
892 892

  
893
<sect2>Attributes
893
<sect1>Attributes
894 894

  
895 895
<p>The Pipe protocol doesn't define any route attributes.
896 896

  
897
<sect2>Example
897
<sect1>Example
898 898

  
899 899
<p>Let's consider a router which serves as a boundary router of two different autonomous
900 900
systems, each of them connected to a subset of interfaces of the router, having its own
......
962 962
}
963 963
</code>
964 964

  
965
<sect1>Rip
965
<sect>Rip
966 966

  
967
<sect2>Introduction
967
<sect1>Introduction
968 968

  
969 969
<p>Rip protocol (sometimes called Rest In Pieces) is a simple protocol, where each router broadcasts
970 970
distances to all networks it can reach. When router hears distance to other network, it increments
......
984 984
very small networks, through.) It is widely used in IPv6 world,
985 985
because they are no good implementations of OSPFv3.
986 986

  
987
<sect2>Configuration
987
<sect1>Configuration
988 988

  
989 989
<p>In addition to options generic to other protocols, rip supports following options:
990 990

  
......
1034 1034
	  </tag>specifies how old route has to be to be discarded. Default is 10*period.
1035 1035
</descrip>
1036 1036

  
1037
<sect2>Attributes
1037
<sect1>Attributes
1038 1038

  
1039 1039
<p>RIP defines two route attributes:
1040 1040

  
......
1048 1048
	in case of external routes).
1049 1049
</descrip>
1050 1050

  
1051
<sect2>Example
1051
<sect1>Example
1052 1052

  
1053 1053
<p><code>
1054 1054
protocol rip MyRIP_test {
......
1064 1064
}
1065 1065
</code>
1066 1066

  
1067
<sect1>Static
1067
<sect>Static
1068 1068

  
1069 1069
<p>The Static protocol doesn't communicate with other routers in the network,
1070 1070
but instead it allows you to define routes manually. This is often used for
......
1111 1111
}
1112 1112
</code>
1113 1113

  
1114
<sect>Problems
1114
<chapt>Problems
1115 1115

  
1116 1116
<p>BIRD is relatively young system, and probably contains some
1117 1117
bugs. You can report bugs at <HTMLURL URL="fixme">, but before you do,
......
1128 1128

  
1129 1129
<p><it/Good luck!/
1130 1130

  
1131
</article>
1131
</book>
1132 1132

  
1133 1133
<!--
1134 1134
LocalWords:  GPL IPv GateD BGPv RIPv OSPFv Linux sgml html dvi sgmltools Pavel
doc/kernel-doc
572 572
    # print out each section
573 573
    $lineprefix="   ";
574 574
    foreach $section (@{$args{'sectionlist'}}) {
575
	print "<sect1>$section\n<p>\n";
575
	print "<sect>$section\n<p>\n";
576 576
	output_highlight($args{'sections'}{$section});
577 577
    }
578 578

  
doc/prog-foot.sgml
1 1

  
2
</article>
2
</book>
doc/prog-head.sgml
6 6
    Copyright (c) 2000 Martin Mares <mj@ucw.cz>
7 7
 -->
8 8

  
9
<article>
9
<book>
10 10

  
11 11
<title>BIRD Programmer's Documentation
12 12
<author>
doc/prog-intro.sgml
1
<sect>BIRD Design
1
<chapt>BIRD Design
2 2

  
3
<sect1>Introduction
3
<sect>Introduction
4 4

  
5 5
<p>This document describes the internal workings of the BIRD, its architecture,
6 6
design decisions and rationale behind them. It also contains documentation on
......
17 17
the most important stuff and leaving the boring technical details better explained
18 18
by the program source itself together with comments contained therein.
19 19

  
20
<sect1>Design goals
20
<sect>Design goals
21 21

  
22 22
<p>When planning the architecture of BIRD, we've taken a close look at the other existing routing
23 23
daemons and also at some of the operating systems used on dedicated routers, gathered all important
......
81 81

  
82 82
</itemize>
83 83

  
84
<sect1>Architecture
84
<sect>Architecture
85 85

  
86 86
<p>The requirements set above have lead to a simple modular architecture containing
87 87
the following types of modules:
......
118 118

  
119 119
</descrip>
120 120

  
121
<sect1>Implementation
121
<sect>Implementation
122 122

  
123 123
<p>BIRD has been written in GNU C. We've considered using of C++, but we've
124 124
preferred the simplicity and straightforward nature of C which gives us fine
doc/prog-proto.sgml
4 4
	(c) 2000 Martin Mares <mj@ucw.cz>
5 5
-->
6 6

  
7
<sect1>Routing protocols
7
<sect>Routing protocols
8 8

  
9
<sect2>Introduction
9
<sect1>Introduction
10 10

  
11 11
<p>The routing protocols are the BIRD's heart and a fine amount of code
12 12
is dedicated to their management and for providing support functions to them.
......
41 41
configuration of protocols, please refer to the configuration chapter and also
42 42
to the description of the <func/proto_commit/ function.
43 43

  
44
<sect2>Protocol states
44
<sect1>Protocol states
45 45

  
46 46
<p>As startup and shutdown of each protocol are complex processes which can be affected
47 47
by lots of external events (user's actions, reconfigurations, behaviour of neighboring routers etc.),
......
86 86
	routing tables.
87 87
</descrip>
88 88

  
89
<sect2>Functions of the protocol module
89
<sect1>Functions of the protocol module
90 90

  
91 91
<p>The protocol module provides the following functions:
tools/progdoc
33 33
    if ($cmd eq "C") { process("$dir/$arg"); }
34 34
    elsif ($cmd eq "H") {
35 35
      push @stack, "H";
36
      print OUT "<sect>$arg\n";
36
      print OUT "<chapt>$arg\n";
37 37
    } elsif ($cmd eq "S") {
38 38
      print "    $arg\n";
39 39
      open(DOC, "cd $srcdir/$dir ; $srcdir/doc/kernel-doc -bird $arg |") || die "Unable to start kernel-doc";

Also available in: Unified diff