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

doc: use RST variable substitutions

Browse Source 
In conf.py, extract & construct values for inline variables throughout
the docs. In the docs, use these inline variables in RST syntax.

Signed-off-by: Quentin Young <qlyoung@cumulusnetworks.com>
This commit is contained in:
Quentin Young 2018-01-19 14:11:06 -05:00
parent c3c5a71ff6
commit be46d28847
No known key found for this signature in database
GPG Key ID: DAF48E0F57E0834F
9 changed files with 96 additions and 80 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

16
doc/user/basic.rst
View File

@ -39,12 +39,12 @@ starting.
Config files are generally found in: Config files are generally found in:
* :file:`@value{INSTALL_PREFIX_ETC}`/\*.conf * :file:`|INSTALL_PREFIX_ETC|`/\*.conf
Each of the daemons has its own Each of the daemons has its own
config file. For example, zebra's default config file name is: config file. For example, zebra's default config file name is:
* :file:`@value{INSTALL_PREFIX_ETC`/zebra.conf} * :file:`INSTALL_PREFIX_ETC`/zebra.conf
The daemon name plus :file:`.conf` is the default config file name. You The daemon name plus :file:`.conf` is the default config file name. You
can specify a config file using the :kbd:`-f` or :kbd:`--config-file` can specify a config file using the :kbd:`-f` or :kbd:`--config-file`
@ -312,7 +312,7 @@ Terminal Mode Commands
.. index:: show version .. index:: show version
``show version`` ``show version``
Show the current version of @value{PACKAGE_NAME} and its build host information. Show the current version of |PACKAGE_NAME| and its build host information.
.. index:: show logging .. index:: show logging
@ -331,7 +331,7 @@ Terminal Mode Commands
Common Invocation Options Common Invocation Options
========================= =========================
These options apply to all @value{PACKAGE_NAME} daemons. These options apply to all |PACKAGE_NAME| daemons.
``-d, --daemon`` ``-d, --daemon``
@ -354,7 +354,7 @@ These options apply to all @value{PACKAGE_NAME} daemons.
The file name is an run-time option rather than a configure-time option 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 so that multiple routing daemons can be run simultaneously. This is
useful when using @value{PACKAGE_NAME} to implement a routing looking glass. One useful when using |PACKAGE_NAME| to implement a routing looking glass. One
machine can be used to collect differing routing views from differing machine can be used to collect differing routing views from differing
points in the network. points in the network.
@ -391,7 +391,7 @@ the following command line option at daemon startup:
Load the specified module, optionally passing options to it. If the module Load the specified module, optionally passing options to it. If the module
name contains a slash (/), it is assumed to be a full pathname to a file to name contains a slash (/), it is assumed to be a full pathname to a file to
be loaded. If it does not contain a slash, the be loaded. If it does not contain a slash, the
`@value{INSTALL_PREFIX_MODULES`} directory is searched for a module of `INSTALL_PREFIX_MODULES` directory is searched for a module of
the given name; first with the daemon name prepended (e.g. ``zebra_mod`` the given name; first with the daemon name prepended (e.g. ``zebra_mod``
for ``mod``), then without the daemon name prepended. for ``mod``), then without the daemon name prepended.
@ -447,8 +447,8 @@ is no VTY password, one cannot connect to the VTY interface at all.
Connected to localhost. Connected to localhost.
Escape character is '^]'. Escape character is '^]'.
Hello, this is @value{PACKAGE_NAME} (version @value{PACKAGE_VERSION}) Hello, this is |PACKAGE_NAME| (version |PACKAGE_VERSION|)
@value{COPYRIGHT_STR} |COPYRIGHT_STR|
User Access Verification User Access Verification

42
doc/user/conf.py
View File

@ -62,7 +62,30 @@ version = u'?.?'
# The full version, including alpha/beta/rc tags. # The full version, including alpha/beta/rc tags.
release = u'?.?-?' 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 # extract version information, installation location, other stuff we need to
# use when building final documents # use when building final documents
@ -70,20 +93,15 @@ val = re.compile('^S\["([^"]+)"\]="(.*)"$')
with open('../../config.status', 'r') as cfgstatus: with open('../../config.status', 'r') as cfgstatus:
for ln in cfgstatus.readlines(): for ln in cfgstatus.readlines():
m = val.match(ln) m = val.match(ln)
if m is None: continue if not m or m.group(1) not in replace_vars.keys(): continue
if m.group(1) == 'PACKAGE_VERSION': replace_vars[m.group(1)] = m.group(2)
release = m.group(2)
version = release.split('-')[0]
if m.group(1) == 'CFG_SYSCONF':
install_prefix_etc = 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 # add substitutions to prolog
rst_prolog += ''' for key, value in replace_vars.items():
.. |INSTALL_PREFIX_ETC| replace:: {} rst_prolog += '.. |{0}| replace:: {1}\n'.format(key, value)
.. |PACKAGE_VERSION| replace:: {}
'''.format(install_prefix_etc, version)
# The language for content autogenerated by Sphinx. Refer to documentation # The language for content autogenerated by Sphinx. Refer to documentation

2
doc/user/defines.rst
View File

@ -12,7 +12,7 @@
@set PACKAGE_VERSION 3.1-dev @set PACKAGE_VERSION 3.1-dev
@set AUTHORS Kunihiro Ishiguro, et al. @set AUTHORS Kunihiro Ishiguro, et al.
@set COPYRIGHT_YEAR 1999-2005 @set COPYRIGHT_YEAR 1999-2005
@set COPYRIGHT_STR Copyright @copyright{} @value{COPYRIGHT_YEAR} @value{AUTHORS} @set COPYRIGHT_STR Copyright @copyright{} |COPYRIGHT_YEAR| |AUTHORS|
@c These may vary with installation environment. @c These may vary with installation environment.
@set INSTALL_PREFIX_ETC /etc/frr @set INSTALL_PREFIX_ETC /etc/frr

2
doc/user/eigrpd.rst
View File

@ -20,7 +20,7 @@ Starting and Stopping eigrpd
The default configuration file name of *eigrpd*'s is The default configuration file name of *eigrpd*'s is
:file:`eigrpd.conf`. When invocation *eigrpd* searches directory :file:`eigrpd.conf`. When invocation *eigrpd* searches directory
@value{INSTALL_PREFIX_ETC}. If :file:`eigrpd.conf` is not there next |INSTALL_PREFIX_ETC|. If :file:`eigrpd.conf` is not there next
search current directory. If an integrated config is specified search current directory. If an integrated config is specified
configuration is written into frr.conf configuration is written into frr.conf

2
doc/user/installation.rst
View File

@ -325,5 +325,5 @@ specify a port number when starting the daemon, these entries may not be
needed. needed.
You may need to make changes to the config files in You may need to make changes to the config files in
:file:`@value{INSTALL_PREFIX_ETC`/\*.conf}. :ref:`Config_Commands`. :file:`|INSTALL_PREFIX_ETC`/\*.conf|. :ref:`Config_Commands`.

2
doc/user/nhrpd.rst
View File

@ -15,7 +15,7 @@ these systems to directly communicate without requiring traffic to use
an intermediate hop. an intermediate hop.
Cisco Dynamic Multipoint VPN (DMVPN) is based on NHRP, and Cisco Dynamic Multipoint VPN (DMVPN) is based on NHRP, and
@value{PACKAGE_NAME} nhrpd implements this scenario. |PACKAGE_NAME| nhrpd implements this scenario.
.. _Routing_Design: .. _Routing_Design:

92
doc/user/overview.rst
View File

@ -6,64 +6,63 @@ Overview
.. index:: Overview .. index:: Overview
`@value{PACKAGE_URL <@value{PACKAGE_URL>`_,,Frr} is a routing software package that `FRR <|PACKAGE_URL|>`_ is a routing software package that provides TCP/IP based
provides TCP/IP based routing services with routing protocols support such routing services with routing protocols support such as RIPv1, RIPv2, RIPng,
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 OSPFv2, OSPFv3, IS-IS, BGP-4, and BGP-4+ (:ref:`Supported_RFCs`). FRR also
behavior. In addition to traditional IPv4 routing protocols, Frr also supports special BGP Route Reflector and Route Server behavior. In addition to
supports IPv6 routing protocols. With SNMP daemon which supports SMUX and AgentX traditional IPv4 routing protocols, FRR also supports IPv6 routing protocols.
protocol, Frr provides routing protocol MIBs (:ref:`SNMP_Support`). 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 FRR uses an advanced software architecture to provide you with a high
quality, multi server routing engine. Frr has an interactive user quality, multi server routing engine. FRR has an interactive user
interface for each routing protocol and supports common client commands. interface for each routing protocol and supports common client commands.
Due to this design, you can add new protocol daemons to Frr easily. You 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. 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 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 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 connect to the Internet your packet will pass many routers which have TCP/IP
routing functionality. 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 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 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. 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, 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 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. 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 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. protocol support for protocols such as RIP, OSPF, IS-IS or BGP.
Traditionally, UNIX based router configuration is done by Traditionally, UNIX based router configuration is done by
*ifconfig* and *route* commands. Status of routing *ifconfig* and *route* commands. Status of routing
table is displayed by *netstat* utility. Almost of these commands table is displayed by *netstat* utility. Almost of these commands
work only if the user has root privileges. Frr has a different system 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 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 mode, the other is enable mode. Normal mode user can only view system
status, enable mode user can change system configuration. This UNIX account status, enable mode user can change system configuration. This UNIX account
independent feature will be great help to the router administrator. 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 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 currently being prepared for merging. Implementations of BFD and PIM-SSM
(IPv4) also exist, but are not actively being worked on. (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. TCP/IP routing software package.
@comment node-name, next, previous, up @comment node-name, next, previous, up
@ -78,7 +77,7 @@ System Architecture
.. index:: Software internals .. index:: Software internals
Traditional routing software is made as a one process program which 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 different approach. It is made from a collection of several daemons that
work together to build the routing table. There may be several work together to build the routing table. There may be several
protocol-specific routing daemons and zebra the kernel routing manager. protocol-specific routing daemons and zebra the kernel routing manager.
@ -110,7 +109,7 @@ architecture creates new possibilities for the routing system.
| | | |
+------------------------------+ +------------------------------+
Frr System Architecture FRR System Architecture
@end group @end group
@ -120,11 +119,11 @@ 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 terminal interface. When you configure a static route, it must be done in
*zebra* configuration file. When you configure BGP network it must *zebra* configuration file. When you configure BGP network it must
be done in *bgpd* configuration file. This can be a very annoying 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 shell called *vtysh*. *vtysh* connects to each daemon with
UNIX domain socket and then works as a proxy for user input. 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 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 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. reliable services such as routing software, so we don't use threads at all.
@ -138,20 +137,20 @@ Supported Platforms
.. index:: Supported platforms .. index:: Supported platforms
.. index:: Frr on other systems .. index:: FRR on other systems
.. index:: Compatibility with 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 to other platforms is not too difficult as platform dependent code should
most be limited to the *zebra* daemon. Protocol daemons are mostly 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. platform which is not listed below.
The list of officially supported platforms are listed below. Note that 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. functionality on further platforms.
@sp 1 @sp 1
@ -178,7 +177,7 @@ may work with some effort:
Mac OSX Mac OSX
Also note that, in particular regarding proprietary platforms, compiler 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: following C compilers are well-tested:
@sp 1 @sp 1
@ -291,18 +290,17 @@ When SNMP support is enabled, below RFC is also supported.
@comment node-name, next, previous, up @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 and contains further information, as well as links to additional
resources. resources.
`@value{PACKAGE_URL <@value{PACKAGE_URL>`_,Frr} is a fork of Quagga, whose FRR is a fork of Quagga, whose website is located at:
web-site is located at:
`http://www.quagga.net/ <http://www.quagga.net/>`_. `http://www.quagga.net/ <http://www.quagga.net/>`_.
@ -311,20 +309,20 @@ web-site is located at:
Mailing List 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:: Contact information
.. index:: Mailing lists .. index:: Mailing lists
There is a mailing list for discussions about Frr. If you have any There is a mailing list for discussions about FRR. If you have any
comments or suggestions to Frr, please subscribe to: comments or suggestions to FRR, please subscribe to:
`https://lists.frrouting.org/listinfo/frog <https://lists.frrouting.org/listinfo/frog>`_. `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: the available mailing lists, see:
`https://lists.frrouting.org/ <https://lists.frrouting.org/>`_ `https://lists.frrouting.org/ <https://lists.frrouting.org/>`_
@ -361,7 +359,7 @@ When you send a bug report, please be careful about the points below.
Please send your configuration file with the report. If you specify Please send your configuration file with the report. If you specify
arguments to the configure script please note that too. arguments to the configure script please note that too.
Bug reports are very important for us to improve the quality of Frr. 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 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>`_. send a bug report to `http://github.com/frrouting/frr/issues <http://github.com/frrouting/frr/issues>`_.

2
doc/user/ripd.rst
View File

@ -23,7 +23,7 @@ Starting and Stopping ripd
The default configuration file name of *ripd*'s is The default configuration file name of *ripd*'s is
:file:`ripd.conf`. When invocation *ripd* searches directory :file:`ripd.conf`. When invocation *ripd* searches directory
@value{INSTALL_PREFIX_ETC}. If :file:`ripd.conf` is not there next |INSTALL_PREFIX_ETC|. If :file:`ripd.conf` is not there next
search current directory. search current directory.
RIP uses UDP port 520 to send and receive RIP packets. So the user must have RIP uses UDP port 520 to send and receive RIP packets. So the user must have

16
doc/user/vtysh.rst
View File

@ -10,7 +10,7 @@ be disabled through the *--disable-vtysh* option to
*./configure*. *./configure*.
*vtysh* has a configuration file, :file:`vtysh.conf`. The location *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 it contains options controlling authentication behavior. This file will
also not be written by configuration-save commands, it is intended to be also not be written by configuration-save commands, it is intended to be
updated manually by an administrator with an external editor. updated manually by an administrator with an external editor.
@ -25,28 +25,28 @@ Permissions and setup requirements
================================== ==================================
*vtysh* connects to running daemons through Unix sockets located in *vtysh* connects to running daemons through Unix sockets located in
:file:`@value{INSTALL_PREFIX_STATE`}. Running vtysh thus requires access to :file:`|INSTALL_PREFIX_STATE|`. Running vtysh thus requires access to
that directory, plus membership in the *@value{INSTALL_VTY_GROUP*} that directory, plus membership in the *|INSTALL_VTY_GROUP|*
group (which is the group that the daemons will change ownership of their group (which is the group that the daemons will change ownership of their
sockets to). sockets to).
To restrict access to Frr configuration, make sure no unauthorized users 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) PAM support (experimental)
-------------------------- --------------------------
vtysh has working (but rather useless) PAM support. It will perform 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 name. No other (accounting, session, password change) calls will be
performed by vtysh. performed by vtysh.
Users using vtysh still need to have appropriate access to the daemons' 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 group. If they have this membership, PAM support is useless since they can
connect to daemons and issue commands using some other tool. Alternatively, connect to daemons and issue commands using some other tool. Alternatively,
the *vtysh* binary could be made SGID (set group ID) to the 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}. made for this configuration}.
.. index:: {Command} {username `username` nopassword} {} .. index:: {Command} {username `username` nopassword} {}
@ -67,7 +67,7 @@ Integrated configuration mode uses a single configuration file,
:file:`frr.conf`, for all daemons. This replaces the individual files like :file:`frr.conf`, for all daemons. This replaces the individual files like
:file:`zebra.conf` or :file:`bgpd.conf`. :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 daemons check for the existence of this file at startup, and if it exists
will not load their individual configuration files. Instead, will not load their individual configuration files. Instead,
*vtysh -b* must be invoked to process :file:`frr.conf` and apply *vtysh -b* must be invoked to process :file:`frr.conf` and apply