proxmox-mirrors/mirror_frr
1
0
Fork 0
mirror of https://git.proxmox.com/git/mirror_frr synced 2025-08-06 00:41:20 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

doc: clean up introductory user docs

Browse Source 
* Update the list of protocol daemons from 5 to the current 13
* Rewrap and clean up formatting for lots of miscellaneous code blocks
* Improve English in various spots
* Update architecture description and diagram
* Remove duplicate information on reporting bugs

Signed-off-by: Quentin Young <qlyoung@cumulusnetworks.com>
This commit is contained in:
Quentin Young 2018-06-06 21:53:09 +00:00
parent db910447b8
commit 2da6ccc392
3 changed files with 184 additions and 224 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

172
doc/user/basic.rst
View File

@ -4,20 +4,7 @@
Basic Commands
**************
There are five routing daemons in use, and there is one manager daemon.
These daemons may be located on separate machines from the manager
daemon. Each of these daemons will listen on a particular port for
incoming VTY connections. The routing daemons are:
- *ripd*
- *ripngd*
- *ospfd*
- *ospf6d*
- *bgpd*
- *zebra*
The following sections discuss commands common to all the routing
daemons.
The following sections discuss commands common to all the routing daemons.
.. _config-commands:
@ -33,9 +20,8 @@ Config Commands
.. index:: Getting the herd running
In a config file, you can write the debugging options, a vty's password,
routing daemon configurations, a log file name, and so forth. This
information forms the initial command set for a routing beast as it is
starting.
routing daemon configurations, a log file name, and so forth. This information
forms the initial command set for a routing beast as it is starting.
Config files are generally found in |INSTALL_PREFIX_ETC|.
@ -50,7 +36,6 @@ Basic Config Commands
---------------------
.. index:: hostname HOSTNAME
.. clicmd:: hostname HOSTNAME
Set hostname of the router.
@ -83,9 +68,9 @@ Basic Config Commands
compatibility. The log trap command sets the current logging level for all
enabled logging destinations, and it sets the default for all future logging
commands that do not specify a level. The normal default logging level is
debugging. The ``no`` form of the command resets the default level for future
logging commands to debugging, but it does not change the logging level of
existing logging destinations.
debugging. The ``no`` form of the command resets the default level for
future logging commands to debugging, but it does not change the logging
level of existing logging destinations.
.. index::
single: no log stdout [LEVEL]
@ -95,12 +80,11 @@ Basic Config Commands
Enable logging output to stdout. If the optional second argument specifying
the logging level is not present, the default logging level (typically
debugging, but can be changed using the deprecated ``log trap`` command) will
be used. The ``no`` form of the command disables logging to stdout. The
``LEVEL`` argument must have one of these values: emergencies, alerts,
critical, errors, warnings, notifications, informational, or debugging. Note
that the existing code logs its most important messages with severity
``errors``.
debugging) will be used. The ``no`` form of the command disables logging to
stdout. The ``LEVEL`` argument must have one of these values: emergencies,
alerts, critical, errors, warnings, notifications, informational, or
debugging. Note that the existing code logs its most important messages with
severity ``errors``.
.. index::
single: no log file [FILENAME [LEVEL]]
@ -109,19 +93,24 @@ Basic Config Commands
.. clicmd:: [no] log file [FILENAME [LEVEL]]
If you want to log into a file, please specify ``filename`` as
in this example: ::
in this example:
log file /var/log/frr/bgpd.log informational
::
log file /var/log/frr/bgpd.log informational
If the optional second argument specifying the logging level is not present,
the default logging level (typically debugging, but can be changed using the
deprecated ``log trap`` command) will be used. The ``no`` form of the command
disables logging to a file. *Note:* if you do not configure any file logging,
and a daemon crashes due to a signal or an assertion failure, it will attempt
to save the crash information in a file named /var/tmp/frr.<daemon
name>.crashlog. For security reasons, this will not happen if the file exists
already, so it is important to delete the file after reporting the crash
information.
disables logging to a file.
.. note::
If you do not configure any file logging, and a daemon crashes due to a
signal or an assertion failure, it will attempt to save the crash
information in a file named :file:`/var/tmp/frr.<daemon name>.crashlog`.
For security reasons, this will not happen if the file exists already, so
it is important to delete the file after reporting the crash information.
.. index::
single: no log syslog [LEVEL]
@ -142,12 +131,11 @@ Basic Config Commands
Enable logging output to vty terminals that have enabled logging using the
``terminal monitor`` command. By default, monitor logging is enabled at the
debugging level, but this command (or the deprecated ``log trap`` command) can
be used to change the monitor logging level. If the optional second argument
specifying the logging level is not present, the default logging level
(typically debugging, but can be changed using the deprecated ``log trap``
command) will be used. The ``no`` form of the command disables logging to
terminal monitors.
debugging level, but this command (or the deprecated ``log trap`` command)
can be used to change the monitor logging level. If the optional second
argument specifying the logging level is not present, the default logging
level (typically debugging) will be used. The ``no`` form of the command
disables logging to terminal monitors.
.. index::
single: no log facility [FACILITY]
@ -156,8 +144,8 @@ Basic Config Commands
.. clicmd:: [no] log facility [FACILITY]
This command changes the facility used in syslog messages. The default
facility is ``daemon``. The ``no`` form of the command resets
the facility to the default ``daemon`` facility.
facility is ``daemon``. The ``no`` form of the command resets the facility
to the default ``daemon`` facility.
.. index::
single: no log record-priority
@ -179,67 +167,59 @@ Basic Config Commands
.. clicmd:: [no] log timestamp precision [(0-6)]
This command sets the precision of log message timestamps to the given number
of digits after the decimal point. Currently, the value must be in the range
0 to 6 (i.e. the maximum precision is microseconds). To restore the default
behavior (1-second accuracy), use the ``no`` form of the command, or set the
precision explicitly to 0.
This command sets the precision of log message timestamps to the given
number of digits after the decimal point. Currently, the value must be in
the range 0 to 6 (i.e. the maximum precision is microseconds). To restore
the default behavior (1-second accuracy), use the ``no`` form of the
command, or set the precision explicitly to 0.
::
::
log timestamp precision 3
log timestamp precision 3
In this example, the precision is set to provide timestamps with
millisecond accuracy.
.. index:: log commands
.. clicmd:: log commands
This command enables the logging of all commands typed by a user to
all enabled log destinations. The note that logging includes full
command lines, including passwords. Once set, command logging can only
be turned off by restarting the daemon.
This command enables the logging of all commands typed by a user to all
enabled log destinations. The note that logging includes full command lines,
including passwords. Once set, command logging can only be turned off by
restarting the daemon.
.. index:: service password-encryption
.. clicmd:: service password-encryption
Encrypt password.
.. index:: service advanced-vty
.. clicmd:: service advanced-vty
Enable advanced mode VTY.
.. index:: service terminal-length (0-512)
.. clicmd:: service terminal-length (0-512)
Set system wide line configuration. This configuration command applies
to all VTY interfaces.
Set system wide line configuration. This configuration command applies to
all VTY interfaces.
.. index:: line vty
.. clicmd:: line vty
Enter vty configuration mode.
.. index:: banner motd default
.. clicmd:: banner motd default
Set default motd string.
.. index:: no banner motd
.. clicmd:: no banner motd
No motd banner string will be printed.
.. index:: exec-timeout MINUTE [SECOND]
.. clicmd:: exec-timeout MINUTE [SECOND]
Set VTY connection timeout value. When only one argument is specified
@ -248,17 +228,17 @@ Basic Config Commands
When timeout value is zero, it means no timeout.
.. index:: no exec-timeout
.. clicmd:: no exec-timeout
Do not perform timeout at all. This command is as same as *exec-timeout 0 0*.
Do not perform timeout at all. This command is as same as
``exec-timeout 0 0``.
.. index:: access-class ACCESS-LIST
.. clicmd:: access-class ACCESS-LIST
Restrict vty connections with an access list.
.. _sample-config-file:
Sample Config File
@ -280,17 +260,17 @@ Below is a sample configuration file for the zebra daemon.
!
'!' and '#' are comment characters. If the first character of the word
is one of the comment characters then from the rest of the line forward
will be ignored as a comment.
``!`` and ``#`` are comment characters. If the first character of the word is
one of the comment characters then from the rest of the line forward will be
ignored as a comment.
.. code-block:: frr
password zebra!password
If a comment character is not the first character of the word, it's a
normal character. So in the above example '!' will not be regarded as a
comment and the password is set to 'zebra!password'.
If a comment character is not the first character of the word, it's a normal
character. So in the above example ``!`` will not be regarded as a comment and
the password is set to ``zebra!password``.
.. _terminal-mode-commands:
@ -298,62 +278,54 @@ Terminal Mode Commands
======================
.. index:: write terminal
.. clicmd:: write terminal
Displays the current configuration to the vty interface.
.. index:: write file
.. clicmd:: write file
Write current configuration to configuration file.
.. index:: configure terminal
.. clicmd:: configure terminal
Change to configuration mode. This command is the first step to
configuration.
.. index:: terminal length (0-512)
.. clicmd:: terminal length (0-512)
Set terminal display length to ``(0-512)``. If length is 0, no
display control is performed.
Set terminal display length to ``(0-512)``. If length is 0, no display
control is performed.
.. index:: who
.. clicmd:: who
Show a list of currently connected vty sessions.
.. index:: list
.. clicmd:: list
List all available commands.
.. index:: show version
.. clicmd:: show version
Show the current version of |PACKAGE_NAME| and its build host information.
.. index:: show logging
.. clicmd:: show logging
Shows the current configuration of the logging system. This includes
the status of all logging destinations.
Shows the current configuration of the logging system. This includes the
status of all logging destinations.
.. index:: logmsg LEVEL MESSAGE
.. clicmd:: logmsg LEVEL MESSAGE
Send a message to all logging destinations that are enabled for messages
of the given severity.
Send a message to all logging destinations that are enabled for messages of
the given severity.
.. _common-invocation-options:
@ -382,16 +354,16 @@ These options apply to all |PACKAGE_NAME| daemons.
to implement commands such as ``.../init.d/zebra status``,
``.../init.d/zebra restart`` or ``.../init.d/zebra stop``.
The file name is an run-time option rather than a configure-time option
so that multiple routing daemons can be run simultaneously. This is
useful when using |PACKAGE_NAME| to implement a routing looking glass. One
machine can be used to collect differing routing views from differing
points in the network.
The file name is an run-time option rather than a configure-time option so
that multiple routing daemons can be run simultaneously. This is useful when
using |PACKAGE_NAME| to implement a routing looking glass. One machine can
be used to collect differing routing views from differing points in the
network.
.. option:: -A, --vty_addr <address>
Set the VTY local address to bind to. If set, the VTY socket will only
be bound to this address.
Set the VTY local address to bind to. If set, the VTY socket will only be
bound to this address.
.. option:: -P, --vty_port <port>
@ -428,15 +400,17 @@ the following command line option at daemon startup:
This option is available on all daemons, though some daemons may not have
any modules available to be loaded.
The SNMP Module
---------------
If SNMP is enabled during compile-time and installed as part of the package,
the ``snmp`` module can be loaded for the *zebra*, *bgpd*, *ospfd*, *ospf6d*
the ``snmp`` module can be loaded for the *Zebra*, *bgpd*, *ospfd*, *ospf6d*
and *ripd* daemons.
The module ignores any options passed to it. Refer to :ref:`snmp-support`
for information on its usage.
The module ignores any options passed to it. Refer to :ref:`snmp-support` for
information on its usage.
The FPM Module
--------------
@ -450,6 +424,7 @@ specifying the encapsulation to use. ``Netlink`` is the default, and
``protobuf`` may not be available if the module was built without protobuf
support. Refer to :ref:`zebra-fib-push-interface` for more information.
.. _virtual-terminal-interfaces:
Virtual Terminal Interfaces
@ -458,6 +433,7 @@ Virtual Terminal Interfaces
VTY -- Virtual Terminal [aka TeletYpe] Interface is a command line
interface (CLI) for user interaction with the routing daemon.
.. _vty-overview:
VTY Overview

5
doc/user/bugs.rst
View File

@ -1,4 +1,7 @@
.. _bugs:
.. index:: Bug Reports
.. index:: Reporting bugs
.. _bug-reports:
**************
Reporting Bugs

231
doc/user/overview.rst
View File

@ -4,19 +4,19 @@
Overview
********
`FRR`_ is a routing software package that provides TCP/IP based
routing services with routing protocols support such as RIPv1, RIPv2, RIPng,
OSPFv2, OSPFv3, IS-IS, BGP-4, and BGP-4+ (:ref:`supported-rfcs`). FRR also
supports special BGP Route Reflector and Route Server behavior. In addition to
`FRR`_ is a routing software package that provides TCP/IP based routing
services with routing protocols support such as RIPv1, RIPv2, RIPng, OSPFv2,
OSPFv3, IS-IS, BGP-4, and BGP-4+ (:ref:`supported-rfcs`). FRR also supports
special BGP Route Reflector and Route Server behavior. In addition to
traditional IPv4 routing protocols, FRR also supports IPv6 routing protocols.
With SNMP daemon which supports SMUX and AgentX protocol, FRR provides routing
protocol MIBs (:ref:`snmp-support`).
FRR uses an advanced software architecture to provide you with a high
quality, multi server routing engine. FRR has an interactive user
interface for each routing protocol and supports common client commands.
Due to this design, you can add new protocol daemons to FRR easily. You
can use FRR library as your program's client user interface.
FRR uses an advanced software architecture to provide you with a high quality,
multi server routing engine. FRR has an interactive user interface for each
routing protocol and supports common client commands. Due to this design, you
can add new protocol daemons to FRR easily. You can use FRR library as your
program's client user interface.
FRR is distributed under the GNU General Public License.
@ -27,43 +27,41 @@ FRR is a fork of `Quagga <http://www.quagga.net/>`_.
About FRR
=========
Today, TCP/IP networks are covering all of the world. The Internet has
been deployed in many countries, companies, and to the home. When you
connect to the Internet your packet will pass many routers which have TCP/IP
routing functionality.
Today, TCP/IP networks are covering all of the world. The Internet has been
deployed in many countries, companies, and to the home. When you connect to
the Internet your packet will pass many routers which have TCP/IP routing
functionality.
A system with FRR installed acts as a dedicated router. With FRR,
your machine exchanges routing information with other routers using routing
protocols. FRR uses this information to update the kernel routing table
so that the right data goes to the right place. You can dynamically change
the configuration and you may view routing table information from the FRR
terminal interface.
A system with FRR installed acts as a dedicated router. With FRR, your machine
exchanges routing information with other routers using routing protocols. FRR
uses this information to update the kernel routing table so that the right data
goes to the right place. You can dynamically change the configuration and you
may view routing table information from the FRR terminal interface.
Adding to routing protocol support, FRR can setup interface's flags,
interface's address, static routes and so on. If you have a small network,
or a stub network, or xDSL connection, configuring the FRR routing
software is very easy. The only thing you have to do is to set up the
interfaces and put a few commands about static routes and/or default routes.
If the network is rather large, or if the network structure changes
frequently, you will want to take advantage of FRR's dynamic routing
protocol support for protocols such as RIP, OSPF, IS-IS or BGP.
interface's address, static routes and so on. If you have a small network, or
a stub network, or xDSL connection, configuring the FRR routing software is
very easy. The only thing you have to do is to set up the interfaces and put a
few commands about static routes and/or default routes. If the network is
rather large, or if the network structure changes frequently, you will want to
take advantage of FRR's dynamic routing protocol support for protocols such as
RIP, OSPF, IS-IS or BGP.
Traditionally, UNIX based router configuration is done by
*ifconfig* and *route* commands. Status of routing
table is displayed by *netstat* utility. Almost of these commands
work only if the user has root privileges. FRR has a different system
administration method. There are two user modes in FRR. One is normal
mode, the other is enable mode. Normal mode user can only view system
status, enable mode user can change system configuration. This UNIX account
independent feature will be great help to the router administrator.
Traditionally, UNIX based router configuration is done by *ifconfig* and
*route* commands. Status of routing table is displayed by *netstat* utility.
Almost of these commands work only if the user has root privileges. FRR has a
different system administration method. There are two user modes in FRR. One
is normal mode, the other is enable mode. Normal mode user can only view
system status, enable mode user can change system configuration. This UNIX
account independent feature will be great help to the router administrator.
Currently, FRR supports common unicast routing protocols, that is BGP,
OSPF, RIP and IS-IS. Upcoming for MPLS support, an implementation of LDP is
Currently, FRR supports common unicast routing protocols, that is BGP, OSPF,
RIP and IS-IS. Upcoming for MPLS support, an implementation of LDP is
currently being prepared for merging. Implementations of BFD and PIM-SSM
(IPv4) also exist, but are not actively being worked on.
The ultimate goal of the FRR project is making a productive, quality, free
TCP/IP routing software package.
The ultimate goal of the FRR project is making a production-grade, high
quality, featureful and free IP routing software suite.
System Architecture
@ -75,79 +73,61 @@ System Architecture
.. index:: Software internals
Traditional routing software is made as a one process program which
provides all of the routing protocol functionalities. FRR takes a
different approach. It is made from a collection of several daemons that
work together to build the routing table. There may be several
protocol-specific routing daemons and zebra the kernel routing manager.
Traditional routing software is made as a one process program which provides
all of the routing protocol functionalities. FRR takes a different approach.
FRR is a suite of daemons that work together to build the routing table. There
is a daemon for each major supported protocol as well as a middleman daemon
(*Zebra*) which serves as the broker between these daemons and the kernel.
The *ripd* daemon handles the RIP protocol, while
*ospfd* is a daemon which supports OSPF version 2.
*bgpd* supports the BGP-4 protocol. For changing the kernel
routing table and for redistribution of routes between different routing
protocols, there is a kernel routing table manager *zebra* daemon.
It is easy to add a new routing protocol daemons to the entire routing
system without affecting any other software. You need to run only the
protocol daemon associated with routing protocols in use. Thus, user may
run a specific daemon and send routing reports to a central routing console.
This architecture allows for high resiliency, since an error, crash or exploit
in one protocol daemon will generally not affect the others. It is also
flexible and extensible since the modularity makes it easy to implement new
protocols and tie them into the suite.
There is no need for these daemons to be running on the same machine. You
can even run several same protocol daemons on the same machine. This
architecture creates new possibilities for the routing system.
An illustration of the large scale architecture is given below.
::
+----+ +----+ +-----+ +-----+
|bgpd| |ripd| |ospfd| |zebra|
+----+ +----+ +-----+ +-----+
|
+---------------------------|--+
| v |
| UNIX Kernel routing table |
| |
+------------------------------+
FRR System Architecture
+----+ +----+ +-----+ +----+ +----+ +----+ +-----+
|bgpd| |ripd| |ospfd| |ldpd| |pbrd| |pimd| |.....|
+----+ +----+ +-----+ +----+ +----+ +----+ +-----+
| | | | | | |
+----v-------v--------v-------v-------v-------v--------v
| |
| Zebra |
| |
+------------------------------------------------------+
| | |
| | |
+------v------+ +---------v--------+ +------v------+
| | | | | |
| *NIX Kernel | | Remote dataplane | | ........... |
| | | | | |
+-------------+ +------------------+ +-------------+
Multi-process architecture brings extensibility, modularity and
maintainability. At the same time it also brings many configuration files
and terminal interfaces. Each daemon has it's own configuration file and
terminal interface. When you configure a static route, it must be done in
*zebra* configuration file. When you configure BGP network it must
be done in *bgpd* configuration file. This can be a very annoying
thing. To resolve the problem, FRR provides integrated user interface
shell called *vtysh*. *vtysh* connects to each daemon with
UNIX domain socket and then works as a proxy for user input.
FRR was planned to use multi-threaded mechanism when it runs with a
kernel that supports multi-threads. But at the moment, the thread library
which comes with GNU/Linux or FreeBSD has some problems with running
reliable services such as routing software, so we don't use threads at all.
Instead we use the *select(2)* system call for multiplexing the
events.
The multi-process architecture brings extensibility, modularity and
maintainability. At the same time it also brings many configuration files and
terminal interfaces. Each daemon has its own configuration file and terminal
interface. When you configure a static route, it must be done in the *Zebra*
configuration file. When you configure BGP network it must be done in the
*bgpd* configuration file. This can become difficult to manage. To resolve the
problem, FRR provides integrated user interface shell called *vtysh*. *vtysh*
connects to each daemon with UNIX domain socket and then works as a proxy for
user input.
Supported Platforms
===================
.. index:: Supported platforms
.. index:: FRR on other systems
.. index:: Compatibility with other systems
.. index:: Operating systems that support FRR
Currently FRR supports GNU/Linux and BSD. Porting FRR
to other platforms is not too difficult as platform dependent code should
most be limited to the *zebra* daemon. Protocol daemons are mostly
platform independent. Please let us know when you find out FRR runs on a
platform which is not listed below.
The list of officially supported platforms are listed below. Note that
FRR may run correctly on other platforms, and may run with partial
functionality on further platforms.
Currently FRR supports GNU/Linux and BSD. Porting FRR to other platforms is not
too difficult as platform dependent code should be mostly limited to the
*Zebra* daemon. Protocol daemons are largely platform independent. Please let
us know if you can get FRR to run on a platform which is not listed below:
- GNU/Linux
- FreeBSD
@ -156,28 +136,51 @@ functionality on further platforms.
Versions of these platforms that are older than around 2 years from the point
of their original release (in case of GNU/Linux, this is since the kernel's
release on https://kernel.org/) may need some work. Similarly, the following platforms
may work with some effort:
release on https://kernel.org/) may need some work. Similarly, the following
platforms may work with some effort:
- Solaris
- MacOS
Also note that, in particular regarding proprietary platforms, compiler
and C library choice will affect FRR. Only recent versions of the
following C compilers are well-tested:
Recent versions of the following compilers are well tested:
- GNU's GCC
- LLVM's clang
- LLVM's Clang
- Intel's ICC
.. _supported-protocols:
Supported Protocols & RFCs
==========================
The following well-known protocols are supported:
- BGP
- Babel
- EIGRP
- IS-IS
- LDP
- NHRP
- OSPFv2
- OSPFv3
- PIM
- RIP
- RIPNG
The following technologies are supported as well:
- PBR (Policy Based Routing)
- VNC (Virtual Network Control)
.. _supported-rfcs:
Supported RFCs
==============
--------------
FRR implements the following RFCs:
.. note:: This list is incomplete.
- :rfc:`1058`
:t:`Routing Information Protocol. C.L. Hedrick. Jun-01-1988.`
- :rfc:`2082`
@ -300,32 +303,10 @@ results of such discussions are reflected in updates, as appropriate, to code
changes, updates to the Development list and either this file or information
posted at `FRR`_.
.. index:: Bug Reports
.. index:: Bug hunting
.. index:: Found a bug?
.. index:: Reporting bugs
.. index:: Reporting software errors
.. index:: Errors in the software
.. _bug-reports:
Bug Reports
===========
If you think you have found a bug, please file a bug report on our
`GitHub issues`_ page.
When you send a bug report, please be careful about the points below.
- Please note what kind of OS you are using. If you use the IPv6 stack
please note that as well.
- Please show us the results of `netstat -rn` and `ifconfig -a`.
Information from zebra's VTY command `show ip route` will also be
helpful.
- Please send your configuration file with the report. If you specify
arguments to the configure script please note that too.
Bug reports help us improve FRR and are very much appreciated.
For information on reporting bugs, please see :ref:`bug-reports`.
.. _frr: |package-url|
.. _github: https://github.com/frrouting/frr/