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:
.. 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|.
---------------------
.. index:: hostname HOSTNAME
-
.. clicmd:: hostname HOSTNAME
Set hostname of the router.
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]
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]]
.. 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]
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]
.. 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
.. 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
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
!
-'!' 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:
======================
.. 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:
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>
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
--------------
``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
VTY -- Virtual Terminal [aka TeletYpe] Interface is a command line
interface (CLI) for user interaction with the routing daemon.
+
.. _vty-overview:
VTY Overview
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.
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.
-
-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
+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.
+
+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
.. 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.
-
-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.
-
-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.
+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.
-::
+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.
+
+An illustration of the large scale architecture is given below.
- +----+ +----+ +-----+ +-----+
- |bgpd| |ripd| |ospfd| |zebra|
- +----+ +----+ +-----+ +-----+
- |
- +---------------------------|--+
- | v |
- | UNIX Kernel routing table |
- | |
- +------------------------------+
-
- FRR System Architecture
-
-
-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.
+::
+ +----+ +----+ +-----+ +----+ +----+ +----+ +-----+
+ |bgpd| |ripd| |ospfd| |ldpd| |pbrd| |pimd| |.....|
+ +----+ +----+ +-----+ +----+ +----+ +----+ +-----+
+ | | | | | | |
+ +----v-------v--------v-------v-------v-------v--------v
+ | |
+ | Zebra |
+ | |
+ +------------------------------------------------------+
+ | | |
+ | | |
+ +------v------+ +---------v--------+ +------v------+
+ | | | | | |
+ | *NIX Kernel | | Remote dataplane | | ........... |
+ | | | | | |
+ +-------------+ +------------------+ +-------------+
+
+
+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
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`
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/
projects / mirror_frr.git / commitdiff