From: Quentin Young Date: Fri, 19 Jan 2018 19:11:06 +0000 (-0500) Subject: doc: use RST variable substitutions X-Git-Tag: frr-5.0-dev~165^2~85 X-Git-Url: https://git.puffer.fish/?a=commitdiff_plain;h=be46d2884737e18c6d0996a17c622b5bff336dee;p=mirror%2Ffrr.git doc: use RST variable substitutions 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 --- diff --git a/doc/user/basic.rst b/doc/user/basic.rst index c46665c501..933d49b01a 100644 --- a/doc/user/basic.rst +++ b/doc/user/basic.rst @@ -39,12 +39,12 @@ starting. Config files are generally found in: -* :file:`@value{INSTALL_PREFIX_ETC}`/\*.conf +* :file:`|INSTALL_PREFIX_ETC|`/\*.conf Each of the daemons has its own 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 can specify a config file using the :kbd:`-f` or :kbd:`--config-file` @@ -312,7 +312,7 @@ Terminal Mode Commands .. index:: 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 @@ -331,7 +331,7 @@ Terminal Mode Commands Common Invocation Options ========================= -These options apply to all @value{PACKAGE_NAME} daemons. +These options apply to all |PACKAGE_NAME| daemons. ``-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 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 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 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 - `@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`` 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. Escape character is '^]'. - Hello, this is @value{PACKAGE_NAME} (version @value{PACKAGE_VERSION}) - @value{COPYRIGHT_STR} + Hello, this is |PACKAGE_NAME| (version |PACKAGE_VERSION|) + |COPYRIGHT_STR| User Access Verification diff --git a/doc/user/conf.py b/doc/user/conf.py index d62e46301c..23ca7d8fe7 100644 --- a/doc/user/conf.py +++ b/doc/user/conf.py @@ -62,7 +62,30 @@ version = u'?.?' # The full version, including alpha/beta/rc tags. release = u'?.?-?' -install_prefix_etc = "" + +# ----------------------------------------------------------------------------- +# 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 @@ -70,20 +93,15 @@ val = re.compile('^S\["([^"]+)"\]="(.*)"$') 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 diff --git a/doc/user/defines.rst b/doc/user/defines.rst index 014d66d0e8..e8c779d3a0 100644 --- a/doc/user/defines.rst +++ b/doc/user/defines.rst @@ -12,7 +12,7 @@ @set PACKAGE_VERSION 3.1-dev @set AUTHORS Kunihiro Ishiguro, et al. @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. @set INSTALL_PREFIX_ETC /etc/frr diff --git a/doc/user/eigrpd.rst b/doc/user/eigrpd.rst index effec5dc1e..7686ef099d 100644 --- a/doc/user/eigrpd.rst +++ b/doc/user/eigrpd.rst @@ -20,7 +20,7 @@ Starting and Stopping eigrpd The default configuration file name of *eigrpd*'s is :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 configuration is written into frr.conf diff --git a/doc/user/installation.rst b/doc/user/installation.rst index 8ede815f7e..4695a08373 100644 --- a/doc/user/installation.rst +++ b/doc/user/installation.rst @@ -325,5 +325,5 @@ specify a port number when starting the daemon, these entries may not be needed. 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`. diff --git a/doc/user/nhrpd.rst b/doc/user/nhrpd.rst index 24037f85b6..a16730a3cc 100644 --- a/doc/user/nhrpd.rst +++ b/doc/user/nhrpd.rst @@ -15,7 +15,7 @@ these systems to directly communicate without requiring traffic to use an intermediate hop. 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: diff --git a/doc/user/overview.rst b/doc/user/overview.rst index 6393d0ba07..204393e2df 100644 --- a/doc/user/overview.rst +++ b/doc/user/overview.rst @@ -6,64 +6,63 @@ Overview .. 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 @@ -78,7 +77,7 @@ 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 +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. @@ -110,7 +109,7 @@ architecture creates new possibilities for the routing system. | | +------------------------------+ - Frr System Architecture + FRR System Architecture @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 *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. @@ -138,20 +137,20 @@ Supported Platforms .. 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 @@ -178,7 +177,7 @@ may work with some effort: 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 @@ -291,18 +290,17 @@ When SNMP support is enabled, below RFC is also supported. @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/ `_. @@ -311,20 +309,20 @@ web-site is located at: 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 `_. -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/ `_ @@ -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 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 `_. diff --git a/doc/user/ripd.rst b/doc/user/ripd.rst index 0aae9bcc39..dc9d7c06d2 100644 --- a/doc/user/ripd.rst +++ b/doc/user/ripd.rst @@ -23,7 +23,7 @@ Starting and Stopping ripd The default configuration file name of *ripd*'s is :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. RIP uses UDP port 520 to send and receive RIP packets. So the user must have diff --git a/doc/user/vtysh.rst b/doc/user/vtysh.rst index d6ed3631a2..a609c2fd7c 100644 --- a/doc/user/vtysh.rst +++ b/doc/user/vtysh.rst @@ -10,7 +10,7 @@ be disabled through the *--disable-vtysh* option to *./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. @@ -25,28 +25,28 @@ Permissions and setup requirements ================================== *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} {} @@ -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:`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