Annotation of embedaddon/bird2/doc/prog-intro.sgml, revision 1.1

1.1     ! misho       1: <chapt>BIRD Design
        !             2: 
        !             3: <sect>Introduction
        !             4: 
        !             5: <p>This document describes the internal workings of BIRD, its architecture,
        !             6: design decisions and rationale behind them. It also contains documentation on
        !             7: all the essential components of the system and their interfaces.
        !             8: 
        !             9: <p>Routing daemons are complicated things which need to act in real time
        !            10: to complex sequences of external events, respond correctly even to the most erroneous behavior
        !            11: of their environment and still handle enormous amount of data with reasonable
        !            12: speed. Due to all of this, their design is very tricky as one needs to carefully
        !            13: balance between efficiency, stability and (last, but not least) simplicity of
        !            14: the program and it would be possible to write literally hundreds of pages about
        !            15: all of these issues. In accordance to the famous quote of Anton Chekhov "Shortness
        !            16: is a sister of talent", we've tried to write a much shorter document highlighting
        !            17: the most important stuff and leaving the boring technical details better explained
        !            18: by the program source itself together with comments contained therein.
        !            19: 
        !            20: <sect>Design goals
        !            21: 
        !            22: <p>When planning the architecture of BIRD, we've taken a close look at the other existing routing
        !            23: daemons and also at some of the operating systems used on dedicated routers, gathered all important
        !            24: features and added lots of new ones to overcome their shortcomings and to better match the requirements
        !            25: of routing in today's Internet: IPv6, policy routing, route filtering and so on. From this
        !            26: planning, the following set of design goals has arisen:
        !            27: 
        !            28: <itemize>
        !            29: 
        !            30: <item><it>Support all the standard routing protocols and make it easy to add new ones.</it>
        !            31: This leads to modularity and clean separation between the core and the protocols.
        !            32: 
        !            33: <item><it>Support both IPv4 and IPv6 in the same source tree, re-using most of the code.</it>
        !            34: This leads to abstraction of IP addresses and operations on them.
        !            35: 
        !            36: <item><it>Minimize OS dependent code to make porting as easy as possible.</it>
        !            37: Unfortunately, such code cannot be avoided at all as the details of communication with
        !            38: the IP stack differ from OS to OS and they often vary even between different
        !            39: versions of the same OS. But we can isolate such code in special modules and
        !            40: do the porting by changing or replacing just these modules.
        !            41: Also, don't rely on specific features of various operating systems, but be able
        !            42: to make use of them if they are available.
        !            43: 
        !            44: <item><it>Allow multiple routing tables.</it>
        !            45: Easily solvable by abstracting out routing tables and the corresponding operations.
        !            46: 
        !            47: <item><it>Offer powerful route filtering.</it>
        !            48: There already were several attempts to incorporate route filters to a dynamic router,
        !            49: but most of them have used simple sequences of filtering rules which were very inflexible
        !            50: and hard to use for non-trivial filters. We've decided to employ a simple loop-free
        !            51: programming language having access to all the route attributes and being able to
        !            52: modify the most of them.
        !            53: 
        !            54: <item><it>Support easy configuration and re-configuration.</it>
        !            55: Most routers use a simple configuration language designed ad hoc with no structure at all
        !            56: and allow online changes of configuration by using their command-line interface, thus
        !            57: any complex re-configurations are hard to achieve without replacing the configuration
        !            58: file and restarting the whole router. We've decided to use a more general approach: to
        !            59: have a configuration defined in a context-free language with blocks and nesting, to
        !            60: perform all configuration changes by editing the configuration file, but to be able
        !            61: to read the new configuration and smoothly adapt to it without disturbing parts of
        !            62: the routing process which are not affected by the change.
        !            63: 
        !            64: <item><it>Be able to be controlled online.</it>
        !            65: In addition to the online reconfiguration, a routing daemon should be able to communicate
        !            66: with the user and with many other programs (primarily scripts used for network maintenance)
        !            67: in order to make it possible to inspect contents of routing tables, status of all
        !            68: routing protocols and also to control their behavior (disable, enable or reset a protocol without restarting all the others). To achieve
        !            69: this, we implement a simple command-line protocol based on those used by FTP and SMTP
        !            70: (that is textual commands and textual replies accompanied by a numeric code which makes
        !            71: them both readable to a human and easy to recognize in software).
        !            72: 
        !            73: <item><it>Respond to all events in real time.</it>
        !            74: A typical solution to this problem is to use lots of threads to separate the workings
        !            75: of all the routing protocols and also of the user interface parts and to hope that
        !            76: the scheduler will assign time to them in a fair enough manner. This is surely a good
        !            77: solution, but we have resisted the temptation and preferred to avoid the overhead of threading
        !            78: and the large number of locks involved and preferred a event driven architecture with
        !            79: our own scheduling of events. An unpleasant consequence of such an approach
        !            80: is that long lasting tasks must be split to more parts linked by special
        !            81: events or timers to make the CPU available for other tasks as well.
        !            82: 
        !            83: </itemize>
        !            84: 
        !            85: <sect>Architecture
        !            86: 
        !            87: <p>The requirements set above have lead to a simple modular architecture containing
        !            88: the following types of modules:
        !            89: 
        !            90: <descrip>
        !            91: 
        !            92: <tagp>Core modules</tagp> implement the core functions of BIRD: taking care
        !            93: of routing tables, keeping protocol status, interacting with the user using
        !            94: the Command-Line Interface (to be called CLI in the rest of this document)
        !            95: etc.
        !            96: 
        !            97: <tagp>Library modules</tagp> form a large set of various library functions
        !            98: implementing several data abstractions, utility functions and also functions
        !            99: which are a part of the standard libraries on some systems, but missing on other
        !           100: ones.
        !           101: 
        !           102: <tagp>Resource management modules</tagp> take care of resources, their allocation
        !           103: and automatic freeing when the module having requested shuts itself down.
        !           104: 
        !           105: <tagp>Configuration modules</tagp> are fragments of lexical analyzer,
        !           106: grammar rules and the corresponding snippets of C code. For each group
        !           107: of code modules (core, each protocol, filters) there exist a configuration
        !           108: module taking care of all the related configuration stuff.
        !           109: 
        !           110: <tagp>The filter</tagp> implements the route filtering language.
        !           111: 
        !           112: <tagp>Protocol modules</tagp> implement the individual routing protocols.
        !           113: 
        !           114: <tagp>System-dependent modules</tagp> implement the interface between BIRD
        !           115: and specific operating systems.
        !           116: 
        !           117: <tagp>The client</tagp> is a simple program providing an easy, though friendly
        !           118: interface to the CLI.
        !           119: 
        !           120: </descrip>
        !           121: 
        !           122: <sect>Implementation
        !           123: 
        !           124: <p>BIRD has been written in GNU C. We've considered using C++, but we've
        !           125: preferred the simplicity and straightforward nature of C which gives us fine
        !           126: control over all implementation details and on the other hand enough
        !           127: instruments to build the abstractions we need.
        !           128: 
        !           129: <p>The modules are statically linked to produce a single executable file
        !           130: (except for the client which stands on its own).
        !           131: 
        !           132: <p>The building process is controlled by a set of Makefiles for GNU Make,
        !           133: intermixed with several Perl and shell scripts.
        !           134: 
        !           135: <p>The initial configuration of the daemon, detection of system features
        !           136: and selection of the right modules to include for the particular OS
        !           137: and the set of protocols the user has chosen is performed by a configure
        !           138: script generated by GNU Autoconf.
        !           139: 
        !           140: <p>The parser of the configuration is generated by the GNU Bison.
        !           141: 
        !           142: <p>The documentation is generated using <file/SGMLtools/ with our own DTD
        !           143: and mapping rules which produce both an online version in HTML and
        !           144: a neatly formatted one for printing (first converted
        !           145: from SGML to &latex; and then processed by &tex; and <file/dvips/ to
        !           146: get a PostScript file).
        !           147: 
        !           148: <p>The comments from C sources which form a part of the programmer's
        !           149: documentation are extracted using a modified version of the <file/kernel-doc/
        !           150: tool.
        !           151: 
        !           152: <p>If you want to work on BIRD, it's highly recommended to configure it
        !           153: with a <tt/--enable-debug/ switch which enables some internal consistency
        !           154: checks and it also links BIRD with a memory allocation checking library
        !           155: if you have one (either <tt/efence/ or <tt/dmalloc/).
        !           156: 
        !           157: <!--
        !           158: LocalWords:  IPv IP CLI snippets Perl Autoconf SGMLtools DTD SGML dvips
        !           159: LocalWords:  PostScript
        !           160:  -->

FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>