doc/user/overview.rst

   1 .. _overview:
   2
   3 ********
   4 Overview
   5 ********
   6
   7 `FRR`_ is a routing software package that provides TCP/IP based
   8 routing services with routing protocols support such as RIPv1, RIPv2, RIPng,
   9 OSPFv2, OSPFv3, IS-IS, BGP-4, and BGP-4+ (:ref:`supported-rfcs`). FRR also
  10 supports special BGP Route Reflector and Route Server behavior.  In addition to
  11 traditional IPv4 routing protocols, FRR also supports IPv6 routing protocols.
  12 With SNMP daemon which supports SMUX and AgentX protocol, FRR provides routing
  13 protocol MIBs (:ref:`snmp-support`).
  14
  15 FRR uses an advanced software architecture to provide you with a high
  16 quality, multi server routing engine. FRR has an interactive user
  17 interface for each routing protocol and supports common client commands.
  18 Due to this design, you can add new protocol daemons to FRR easily.  You
  19 can use FRR library as your program's client user interface.
  20
  21 FRR is distributed under the GNU General Public License.
  22
  23 .. _about-frr:
  24
  25 About FRR
  26 =========
  27
  28 Today, TCP/IP networks are covering all of the world.  The Internet has
  29 been deployed in many countries, companies, and to the home.  When you
  30 connect to the Internet your packet will pass many routers which have TCP/IP
  31 routing functionality.
  32
  33 A system with FRR installed acts as a dedicated router.  With FRR,
  34 your machine exchanges routing information with other routers using routing
  35 protocols.  FRR uses this information to update the kernel routing table
  36 so that the right data goes to the right place.  You can dynamically change
  37 the configuration and you may view routing table information from the FRR
  38 terminal interface.
  39
  40 Adding to routing protocol support, FRR can setup interface's flags,
  41 interface's address, static routes and so on.  If you have a small network,
  42 or a stub network, or xDSL connection, configuring the FRR routing
  43 software is very easy.  The only thing you have to do is to set up the
  44 interfaces and put a few commands about static routes and/or default routes.
  45 If the network is rather large, or if the network structure changes
  46 frequently, you will want to take advantage of FRR's dynamic routing
  47 protocol support for protocols such as RIP, OSPF, IS-IS or BGP.
  48
  49 Traditionally, UNIX based router configuration is done by
  50 *ifconfig* and *route* commands.  Status of routing
  51 table is displayed by *netstat* utility.  Almost of these commands
  52 work only if the user has root privileges.  FRR has a different system
  53 administration method.  There are two user modes in FRR.  One is normal
  54 mode, the other is enable mode.  Normal mode user can only view system
  55 status, enable mode user can change system configuration.  This UNIX account
  56 independent feature will be great help to the router administrator.
  57
  58 Currently, FRR supports common unicast routing protocols, that is BGP,
  59 OSPF, RIP and IS-IS.  Upcoming for MPLS support, an implementation of LDP is
  60 currently being prepared for merging.  Implementations of BFD and PIM-SSM
  61 (IPv4) also exist, but are not actively being worked on.
  62
  63 The ultimate goal of the FRR project is making a productive, quality, free
  64 TCP/IP routing software package.
  65
  66
  67 System Architecture
  68 ===================
  69
  70 .. index:: System architecture
  71
  72 .. index:: Software architecture
  73
  74 .. index:: Software internals
  75
  76 Traditional routing software is made as a one process program which
  77 provides all of the routing protocol functionalities.  FRR takes a
  78 different approach.  It is made from a collection of several daemons that
  79 work together to build the routing table.  There may be several
  80 protocol-specific routing daemons and zebra the kernel routing manager.
  81
  82 The *ripd* daemon handles the RIP protocol, while
  83 *ospfd* is a daemon which supports OSPF version 2.
  84 *bgpd* supports the BGP-4 protocol.  For changing the kernel
  85 routing table and for redistribution of routes between different routing
  86 protocols, there is a kernel routing table manager *zebra* daemon.
  87 It is easy to add a new routing protocol daemons to the entire routing
  88 system without affecting any other software.  You need to run only the
  89 protocol daemon associated with routing protocols in use.  Thus, user may
  90 run a specific daemon and send routing reports to a central routing console.
  91
  92 There is no need for these daemons to be running on the same machine. You
  93 can even run several same protocol daemons on the same machine.  This
  94 architecture creates new possibilities for the routing system.
  95
  96 ::
  97
  98    +----+  +----+  +-----+  +-----+
  99    |bgpd|  |ripd|  |ospfd|  |zebra|
 100    +----+  +----+  +-----+  +-----+
 101                                |
 102    +---------------------------|--+
 103    |                           v  |
 104    |  UNIX Kernel  routing table  |
 105    |                              |
 106    +------------------------------+
 107
 108        FRR System Architecture
 109
 110
 111 Multi-process architecture brings extensibility, modularity and
 112 maintainability.  At the same time it also brings many configuration files
 113 and terminal interfaces.  Each daemon has it's own configuration file and
 114 terminal interface.  When you configure a static route, it must be done in
 115 *zebra* configuration file.  When you configure BGP network it must
 116 be done in *bgpd* configuration file.  This can be a very annoying
 117 thing.  To resolve the problem, FRR provides integrated user interface
 118 shell called *vtysh*.  *vtysh* connects to each daemon with
 119 UNIX domain socket and then works as a proxy for user input.
 120
 121 FRR was planned to use multi-threaded mechanism when it runs with a
 122 kernel that supports multi-threads.  But at the moment, the thread library
 123 which comes with GNU/Linux or FreeBSD has some problems with running
 124 reliable services such as routing software, so we don't use threads at all.
 125 Instead we use the *select(2)* system call for multiplexing the
 126 events.
 127
 128
 129 Supported Platforms
 130 ===================
 131
 132 .. index:: Supported platforms
 133
 134 .. index:: FRR on other systems
 135
 136 .. index:: Compatibility with other systems
 137
 138 .. index:: Operating systems that support FRR
 139
 140 Currently FRR supports GNU/Linux and BSD. Porting FRR
 141 to other platforms is not too difficult as platform dependent code should
 142 most be limited to the *zebra* daemon.  Protocol daemons are mostly
 143 platform independent. Please let us know when you find out FRR runs on a
 144 platform which is not listed below.
 145
 146 The list of officially supported platforms are listed below. Note that
 147 FRR may run correctly on other platforms, and may run with partial
 148 functionality on further platforms.
 149
 150 - GNU/Linux
 151 - FreeBSD
 152 - NetBSD
 153 - OpenBSD
 154
 155 Versions of these platforms that are older than around 2 years from the point
 156 of their original release (in case of GNU/Linux, this is since the kernel's
 157 release on https://kernel.org/) may need some work.  Similarly, the following platforms
 158 may work with some effort:
 159
 160 - Solaris
 161 - MacOS
 162
 163 Also note that, in particular regarding proprietary platforms, compiler
 164 and C library choice will affect FRR.  Only recent versions of the
 165 following C compilers are well-tested:
 166
 167 - GNU's GCC
 168 - LLVM's clang
 169 - Intel's ICC
 170
 171
 172 .. _supported-rfcs:
 173
 174 Supported RFCs
 175 ==============
 176
 177 FRR implements the following RFCs:
 178
 179 - :rfc:`1058`
 180   :t:`Routing Information Protocol. C.L. Hedrick. Jun-01-1988.`
 181 - :rfc:`2082`
 182   :t:`RIP-2 MD5 Authentication. F. Baker, R. Atkinson. January 1997.`
 183 - :rfc:`2453`
 184   :t:`RIP Version 2. G. Malkin. November 1998.`
 185 - :rfc:`2080`
 186   :t:`RIPng for IPv6. G. Malkin, R. Minnear. January 1997.`
 187 - :rfc:`2328`
 188   :t:`OSPF Version 2. J. Moy. April 1998.`
 189 - :rfc:`2370`
 190   :t:`The OSPF Opaque LSA Option R. Coltun. July 1998.`
 191 - :rfc:`3101`
 192   :t:`The OSPF Not-So-Stubby Area (NSSA) Option P. Murphy. January 2003.`
 193 - :rfc:`2740`
 194   :t:`OSPF for IPv6. R. Coltun, D. Ferguson, J. Moy. December 1999.`
 195 - :rfc:`1771`
 196   :t:`A Border Gateway Protocol 4 (BGP-4). Y. Rekhter & T. Li. March 1995.`
 197 - :rfc:`1965`
 198   :t:`Autonomous System Confederations for BGP. P. Traina. June 1996.`
 199 - :rfc:`1997`
 200   :t:`BGP Communities Attribute. R. Chandra, P. Traina & T. Li. August 1996.`
 201 - :rfc:`2545`
 202   :t:`Use of BGP-4 Multiprotocol Extensions for IPv6 Inter-Domain Routing. P.
 203   Marques, F. Dupont. March 1999.`
 204 - :rfc:`2796`
 205   :t:`BGP Route Reflection An alternative to full mesh IBGP. T. Bates & R.
 206   Chandrasekeran. June 1996.`
 207 - :rfc:`2858`
 208   :t:`Multiprotocol Extensions for BGP-4. T. Bates, Y. Rekhter, R. Chandra, D.
 209   Katz. June 2000.`
 210 - :rfc:`2842`
 211   :t:`Capabilities Advertisement with BGP-4. R. Chandra, J. Scudder. May 2000.`
 212 - :rfc:`3137`
 213   :t:`OSPF Stub Router Advertisement, A. Retana, L. Nguyen, R. White, A. Zinin,
 214   D. McPherson. June 2001`
 215
 216 **When SNMP support is enabled, the following RFCs are also supported:**
 217
 218 - :rfc:`1227`
 219   :t:`SNMP MUX protocol and MIB. M.T. Rose. May-01-1991.`
 220 - :rfc:`1657`
 221   :t:`Definitions of Managed Objects for the Fourth Version of the Border
 222   Gateway Protocol (BGP-4) using SMIv2. S. Willis, J. Burruss, J. Chu, Editor.
 223   July 1994.`
 224 - :rfc:`1724`
 225   :t:`RIP Version 2 MIB Extension. G. Malkin & F. Baker. November 1994.`
 226 - :rfc:`1850`
 227   :t:`OSPF Version 2 Management Information Base. F. Baker, R. Coltun.
 228   November 1995.`
 229 - :rfc:`2741`
 230   :t:`Agent Extensibility (AgentX) Protocol. M. Daniele, B. Wijnen. January 2000.`
 231
 232 How to get FRR
 233 ==============
 234
 235 The official FRR website is located at |PACKAGE_URL| and contains further
 236 information, as well as links to additional resources.
 237
 238 FRR is a fork of `Quagga <http://www.quagga.net/>`_.
 239
 240 Mailing Lists
 241 =============
 242
 243 .. index:: How to get in touch with FRR
 244 .. index:: Contact information
 245 .. index:: Mailing lists
 246
 247
 248 Italicized lists are private.
 249
 250 +--------------------------------+------------------------------+
 251 | Topic                          | List                         |
 252 +================================+==============================+
 253 | Development                    | dev@lists.frrouting.org      |
 254 +--------------------------------+------------------------------+
 255 | Users & Operators              | frog@lists.frrouting.org     |
 256 +--------------------------------+------------------------------+
 257 | Announcements                  | announce@lists.frrouting.org |
 258 +--------------------------------+------------------------------+
 259 | *Security*                     | security@lists.frrouting.org |
 260 +--------------------------------+------------------------------+
 261 | *Technical Steering Committee* | tsc@lists.frrouting.org      |
 262 +--------------------------------+------------------------------+
 263
 264 The Development list is used to discuss and document general issues related to
 265 project development and governance. The public `Slack`_ instance and weekly
 266 technical meetings provide a higher bandwidth channel for discussions. The
 267 results of such discussions are reflected in updates, as appropriate, to code
 268 (i.e., merges), `GitHub issues`_ tracked issues, and for governance or process
 269 changes, updates to the Development list and either this file or information
 270 posted at `FRR`_.
 271
 272 .. index:: Bug Reports
 273 .. index:: Bug hunting
 274 .. index:: Found a bug?
 275 .. index:: Reporting bugs
 276 .. index:: Reporting software errors
 277 .. index:: Errors in the software
 278
 279 .. _bug-reports:
 280
 281 Bug Reports
 282 ===========
 283
 284 If you think you have found a bug, please file a bug report on our
 285 `GitHub issues`_ page.
 286
 287 When you send a bug report, please be careful about the points below.
 288
 289 - Please note what kind of OS you are using.  If you use the IPv6 stack
 290   please note that as well.
 291 - Please show us the results of `netstat -rn` and `ifconfig -a`.
 292   Information from zebra's VTY command `show ip route` will also be
 293   helpful.
 294 - Please send your configuration file with the report.  If you specify
 295   arguments to the configure script please note that too.
 296
 297 Bug reports help us improve FRR and are very much appreciated.
 298
 299 .. _frr: |package-url|
 300 .. _github: https://github.com/frrouting/frr/
 301 .. _github issues: https://github.com/frrouting/frr/issues
 302 .. _slack: https://frrouting.slack.com/