# The full version, including alpha/beta/rc tags.
release = u'?.?-?'
-install_prefix_etc = "<install_prefix>"
+
+# -----------------------------------------------------------------------------
+# Extract values from codebase for substitution into docs.
+# -----------------------------------------------------------------------------
+
+# Various installation prefixes. Reasonable defaults are set where possible.
+# Values are overridden by logic below.
+replace_vars = {
+ 'AUTHORS': 'Kunihiro Ishiguro, et al.',
+ 'COPYRIGHT_YEAR': '1999-2005',
+ 'COPYRIGHT_STR': None,
+ 'PACKAGE_NAME': project.lower(),
+ 'PACKAGE_TARNAME': project.lower(),
+ 'PACKAGE_STRING': None,
+ 'PACKAGE_URL': 'https://frrouting.org/',
+ 'PACKAGE_VERSION': None,
+ 'INSTALL_PREFIX_ETC': None,
+ 'INSTALL_PREFIX_SBIN': None,
+ 'INSTALL_PREFIX_STATE': None,
+ 'INSTALL_PREFIX_MODULES': None,
+ 'INSTALL_USER': None,
+ 'INSTALL_GROUP': None,
+ 'INSTALL_VTY_GROUP': None,
+}
# extract version information, installation location, other stuff we need to
# use when building final documents
with open('../../config.status', 'r') as cfgstatus:
for ln in cfgstatus.readlines():
m = val.match(ln)
- if m is None: continue
- if m.group(1) == 'PACKAGE_VERSION':
- release = m.group(2)
- version = release.split('-')[0]
- if m.group(1) == 'CFG_SYSCONF':
- install_prefix_etc = m.group(2)
+ if not m or m.group(1) not in replace_vars.keys(): continue
+ replace_vars[m.group(1)] = m.group(2)
+# manually fill out some of these we can't get from config.status
+replace_vars['COPYRIGHT_STR'] = "Copyright (c) {} {}".format(replace_vars['COPYRIGHT_YEAR'], replace_vars['AUTHORS'])
# add substitutions to prolog
-rst_prolog += '''
-.. |INSTALL_PREFIX_ETC| replace:: {}
-.. |PACKAGE_VERSION| replace:: {}
-'''.format(install_prefix_etc, version)
-
+for key, value in replace_vars.items():
+ rst_prolog += '.. |{0}| replace:: {1}\n'.format(key, value)
# The language for content autogenerated by Sphinx. Refer to documentation
.. index:: Overview
-`@value{PACKAGE_URL <@value{PACKAGE_URL>`_,,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
+`FRR <|PACKAGE_URL|>`_ 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.
+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 @sc{gnu} General Public License.
+FRR is distributed under the GNU General Public License.
-@comment node-name, next, previous, up
-
-About Frr
+About FRR
=========
-.. index:: About Frr
+.. index:: 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.
-A system with Frr installed acts as a dedicated router. With Frr,
+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
+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
+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,
+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
+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
+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
+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,
+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
+The ultimate goal of the FRR project is making a productive, quality, free
TCP/IP routing software package.
@comment node-name, next, previous, up
.. index:: Software internals
Traditional routing software is made as a one process program which
-provides all of the routing protocol functionalities. Frr takes a
+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.
| |
+------------------------------+
- Frr System Architecture
+ FRR System Architecture
@end group
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
+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
+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 @sc{gnu}/Linux or FreeBSD has some problems with running
reliable services such as routing software, so we don't use threads at all.
.. index:: Supported platforms
-.. index:: Frr on other systems
+.. index:: FRR on other systems
.. index:: Compatibility with other systems
-.. index:: Operating systems that support Frr
+.. index:: Operating systems that support FRR
-Currently Frr supports @sc{gnu}/Linux and BSD. Porting Frr
+Currently FRR supports @sc{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 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
+FRR may run correctly on other platforms, and may run with partial
functionality on further platforms.
@sp 1
Mac OSX
Also note that, in particular regarding proprietary platforms, compiler
-and C library choice will affect Frr. Only recent versions of the
+and C library choice will affect FRR. Only recent versions of the
following C compilers are well-tested:
@sp 1
@comment node-name, next, previous, up
-How to get Frr
+How to get FRR
==============
-The official Frr web-site is located at:
+The official FRR web-site is located at:
-`@value{PACKAGE_URL <@value{PACKAGE_URL>`_}
+`|PACKAGE_URL| <|PACKAGE_URL|>`_
and contains further information, as well as links to additional
resources.
-`@value{PACKAGE_URL <@value{PACKAGE_URL>`_,Frr} is a fork of Quagga, whose
-web-site is located at:
+FRR is a fork of Quagga, whose website is located at:
`http://www.quagga.net/ <http://www.quagga.net/>`_.
Mailing List
============
-.. index:: How to get in touch with Frr
+.. index:: How to get in touch with FRR
-.. index:: Mailing Frr
+.. index:: Mailing FRR
.. index:: Contact information
.. index:: Mailing lists
-There is a mailing list for discussions about Frr. If you have any
-comments or suggestions to Frr, please subscribe to:
+There is a mailing list for discussions about FRR. If you have any
+comments or suggestions to FRR, please subscribe to:
`https://lists.frrouting.org/listinfo/frog <https://lists.frrouting.org/listinfo/frog>`_.
-The `@value{PACKAGE_URL <@value{PACKAGE_URL>`_,,Frr} site has further information on
+The `FRR <|PACKAGE_URL|>`_ site has further information on
the available mailing lists, see:
`https://lists.frrouting.org/ <https://lists.frrouting.org/>`_
Please send your configuration file with the report. If you specify
arguments to the configure script please note that too.
-Bug reports are very important for us to improve the quality of Frr.
-Frr is still in the development stage, but please don't hesitate to
+Bug reports are very important for us to improve the quality of FRR.
+FRR is still in the development stage, but please don't hesitate to
send a bug report to `http://github.com/frrouting/frr/issues <http://github.com/frrouting/frr/issues>`_.
*./configure*.
*vtysh* has a configuration file, :file:`vtysh.conf`. The location
-of that file cannot be changed from :file:`@value{INSTALL_PREFIX_ETC`} since
+of that file cannot be changed from :file:`|INSTALL_PREFIX_ETC|` since
it contains options controlling authentication behavior. This file will
also not be written by configuration-save commands, it is intended to be
updated manually by an administrator with an external editor.
==================================
*vtysh* connects to running daemons through Unix sockets located in
-:file:`@value{INSTALL_PREFIX_STATE`}. Running vtysh thus requires access to
-that directory, plus membership in the *@value{INSTALL_VTY_GROUP*}
+:file:`|INSTALL_PREFIX_STATE|`. Running vtysh thus requires access to
+that directory, plus membership in the *|INSTALL_VTY_GROUP|*
group (which is the group that the daemons will change ownership of their
sockets to).
To restrict access to Frr configuration, make sure no unauthorized users
-are members of the *@value{INSTALL_VTY_GROUP*} group.
+are members of the *|INSTALL_VTY_GROUP|* group.
PAM support (experimental)
--------------------------
vtysh has working (but rather useless) PAM support. It will perform
-an "authenticate" PAM call using *@value{PACKAGE_NAME*} as service
+an "authenticate" PAM call using *|PACKAGE_NAME|* as service
name. No other (accounting, session, password change) calls will be
performed by vtysh.
Users using vtysh still need to have appropriate access to the daemons'
-VTY sockets, usually by being member of the *@value{INSTALL_VTY_GROUP*}
+VTY sockets, usually by being member of the *|INSTALL_VTY_GROUP|*
group. If they have this membership, PAM support is useless since they can
connect to daemons and issue commands using some other tool. Alternatively,
the *vtysh* binary could be made SGID (set group ID) to the
-*@value{INSTALL_VTY_GROUP*} group. @strong{No security guarantees are
+*|INSTALL_VTY_GROUP|* group. @strong{No security guarantees are
made for this configuration}.
.. index:: {Command} {username `username` nopassword} {}
:file:`frr.conf`, for all daemons. This replaces the individual files like
:file:`zebra.conf` or :file:`bgpd.conf`.
-:file:`frr.conf` is located in :file:`@value{INSTALL_PREFIX_ETC`}. All
+:file:`frr.conf` is located in :file:`|INSTALL_PREFIX_ETC|`. All
daemons check for the existence of this file at startup, and if it exists
will not load their individual configuration files. Instead,
*vtysh -b* must be invoked to process :file:`frr.conf` and apply
projects / mirror / frr.git / commitdiff