diff --git a/Doc b/Doc index 0ba53c65..512160a5 100644 --- a/Doc +++ b/Doc @@ -1,3 +1,4 @@ +D prog-intro.sgml C lib C nest C conf diff --git a/TODO b/TODO index 68195106..ecf00d81 100644 --- a/TODO +++ b/TODO @@ -80,6 +80,7 @@ o "About routing tables" by melo byt podstatne podrobnejsi (vysvetlit, co vlast ze lze prenaset routy mezi tabulkami (odkaz na protokol pipe), ze k tabulkam jsou pres filtry pripojeny protokoly atd.) Asi z toho udelat samostatnou kapitolu. o Zminit logy a kategorie hlasek. +o Chybi installation requirements: tedy ze potrebujeme GCC a GNU make. Filtry: diff --git a/doc/prog-intro.sgml b/doc/prog-intro.sgml new file mode 100644 index 00000000..18637feb --- /dev/null +++ b/doc/prog-intro.sgml @@ -0,0 +1,151 @@ +BIRD Design + +Introduction + +

This document describes the internal workings of the BIRD, its architecture, +design decisions and rationale behind them. It also contains documentation on +all the essential components of the system and their interfaces. + +

Routing daemons are very complicated things which need to act in real time +to complex sequences external events, react correctly even to the most erroneous behavior +of their environment and still handle enormous amount of data with reasonable +speed. Due to all of this, their design is very tricky as one needs to carefully +balance between efficiency, stability and (last, but not least) simplicity of +the program and it would be possible to write literally hundreds of pages about +all of these issues. In accordance to the famous quote of Anton Chekhov "Shortness +is a sister of talent", we've tried to write a much shorter document highlighting +the most important stuff and leaving the boring technical details better explained +by the program source itself together with comments contained therein. + +Design goals + +

When planning the architecture of BIRD, we've taken a close look at the other existing routing +daemons and also at some of the operating systems used on dedicated routers, gathered all important +features and added lots of new ones to overcome their shortcomings and better match the requirements +of routing in today's Internet: IPv6, policy routing, route filtering and so on. From this +planning, the following set of design goals has arisen: + + + +Support all the standard routing protocols and make it easy to add new ones. +This leads to modularity and clean separation between the core and the protocols. + +Support both IPv4 and IPv6 in the same source tree, re-using most of the code. +This leads to abstraction of IP addresses and operations on them. + +Minimize OS dependent code to make porting as easy as possible. +Unfortunately, such code cannot be avoided at all as the details of communication with +the IP stack differ from OS to OS and they often vary even between different +versions of the same OS, but we can isolate such code in special modules and +do the porting by changing just these modules. +Also, don't rely on specific features of various operating systems, but be able +to make use of them if they are available. + +Allow multiple routing tables. +Easily solvable by abstracting out routing tables and the corresponding operations. + +Offer powerful route filtering. +There already were several attempts to incorporate route filters to a dynamic router, +but most of them have used simple sequences of filtering rules which were very inflexible +and hard to use for any non-trivial filters. We've decided to employ a simple loop-free +programming language having access to all the route attributes and being able to +modify the most of them. + +Support easy configuration and re-configuration. +Most routers use a simple configuration language designed ad hoc with no structure at all +and allow online changes of configuration by using their command-line interface, thus +any complex re-configurations are hard to achieve without replacing the configuration +file and restarting the whole router. We've decided to use a more general approach: to +have a configuration defined in a context-free language with blocks and nesting, to +perform all configuration changes by editing the configuration file, but to be able +to read the new configuration and smoothly adapt to it without disturbing parts of +the routing process which are not affected by the change. + +Be able to be controlled online. +In addition to online reconfiguration, a routing daemon should be able to communicate +with the user and with many other programs (primarily scripts used for network maintenance) +in order to make it possible to inspect contents of routing tables, status of all +routing protocols and also to control their behavior (i.e., it should be possible +to disable, enable or reset a protocol without restarting all the others). To achieve +this, we implement a simple command-line protocol based on those used by FTP and SMTP +(that is textual commands and textual replies accompanied by a numeric code which makes +them both readable to a human and easy to recognize in software). + +Respond to all protocol events in real time. +A typical solution to this problem is to use lots of threads to separate the workings +of all the routing protocols and also of the user interface parts and to hope that +the scheduler will assign time to them in a fair enough manner. This is surely a good +solution, but we have resisted the temptation and preferred to avoid the overhead of threading +and the large number of locks involved and preferred a event driven architecture with +our own scheduling of events. + + + +Architecture + +

The requirements set above have lead to a simple modular architecture containing +the following types of modules: + + + +Core modules implement the core functions of BIRD as taking care +of routing tables, keeping protocol status, interacting with the user using +the Command-Line Interface (to be called CLI in the rest of this document) +etc. + +Library modules form a large set of various library functions +implementing several data abstractions, utility functions and also functions +which are a part of standard libraries on some systems, but missing on other +ones. + +Resource management modules take care of resources, their allocation +and automatic freeing when the module having requested them ceases to exist. + +Configuration modules are fragments of lexical analyzer, +grammar rules and the corresponding snippets of C code. For each group +of code modules (core, each protocol, filters) there exist a configuration +module taking care of all the related configuration stuff. + +Filters implement the route filtering language. + +Protocol modules implement the individual routing protocols. + +System-dependent modules implement the interface between BIRD +and specific operating systems. + +The client is a simple program providing an easy, though friendly +interface to the CLI. + + + +Implementation + +

BIRD has been written in GNU C. We've considered using of C++, but we've +preferred the simplicity and straightforward nature of C which gives us fine +control over all implementation details and on the other hand enough +instruments to build the abstractions we need. + +

The building process is controlled by a set of Makefiles for GNU Make, +intermixed with several Perl and shell scripts. + +

The initial configuration of the daemon, detection of system features +and selection of the right modules to include for the particular OS +and the set of protocols the user has chosen is performed by a configure +script created using GNU Autoconf. + +

The parser of the configuration is generated by the GNU Bison. + +

The documentation is generated using and then processed by and The comments from C sources which form a part of the programmer's +documentation are extracted using a modified version of the diff --git a/lib/Doc b/lib/Doc index f1579a3e..bf1b4060 100644 --- a/lib/Doc +++ b/lib/Doc @@ -2,11 +2,13 @@ H Library S checksum.c md5.c S ip.c ipv4.c ipv6.c S lists.c -S mempool.c -S slab.c -S socket.h S bitops.c -S event.c S patmatch.c S printf.c S unaligned.h +H Resource management +S resource.c +S mempool.c +S slab.c +S socket.h +S event.c