From 73edff0a21f8486a2c416537b72dda60c1885462 Mon Sep 17 00:00:00 2001 From: Christian Poessinger Date: Sun, 17 Nov 2019 20:20:16 +0100 Subject: Replace all RFC links with proper :rfc: syntax --- docs/contributing/documentation.rst | 10 +++------- docs/interfaces/addresses.rst | 13 ++++--------- docs/interfaces/l2tpv3.rst | 3 +-- docs/interfaces/pppoe.rst | 4 +--- docs/interfaces/tunnel.rst | 10 +++------- docs/interfaces/vxlan.rst | 8 +------- docs/nat.rst | 9 +++------ docs/qos.rst | 7 ++----- docs/routing/static.rst | 4 +--- docs/services/dynamic-dns.rst | 5 ++--- docs/services/lldp.rst | 2 +- docs/services/references.rst | 1 - docs/vpn/dmvpn.rst | 11 +++-------- docs/vpn/references.rst | 3 --- docs/vpn/site2site_ipsec.rst | 7 +++---- 15 files changed, 28 insertions(+), 69 deletions(-) diff --git a/docs/contributing/documentation.rst b/docs/contributing/documentation.rst index 7beee976..7d8ebba2 100644 --- a/docs/contributing/documentation.rst +++ b/docs/contributing/documentation.rst @@ -35,9 +35,9 @@ This requires you already have a GitHub account. describing your change. Please check the documentation if you aren't familiar with Sphinx-doc_ or reStructuredText_. - Note the following RFCs (RFC5737_, RFC3849_, RFC5389_ and RFC7042_), which - describe the reserved public IP addresses and autonomous system numbers for - the documentation: + Note the following RFCs (:rfc:`5737`, :rfc:`3849`, :rfc:`5389` and + :rfc:`7042`), which describe the reserved public IP addresses and autonomous + system numbers for the documentation: * ``192.0.2.0/24`` * ``198.51.100.0/24`` @@ -92,10 +92,6 @@ This requires you already have a GitHub account. If you want to update your fork on GitHub, too use the following: ``$ git push origin master`` -.. _RFC5737: https://tools.ietf.org/html/rfc5737 -.. _RFC3849: https://tools.ietf.org/html/rfc3849 -.. _RFC5389: https://tools.ietf.org/html/rfc5398 -.. _RFC7042: https://tools.ietf.org/html/ .. _Sphinx-doc: https://www.sphinx-doc.org .. _reStructuredText: http://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html .. _Phabricator: https://phabricator.vyos.net diff --git a/docs/interfaces/addresses.rst b/docs/interfaces/addresses.rst index 51d2e7e5..0ced23f8 100644 --- a/docs/interfaces/addresses.rst +++ b/docs/interfaces/addresses.rst @@ -87,7 +87,7 @@ The command is `set interfaces $type $name address dhcpv6`. Examples: Autoconfiguration (SLAAC) ************************* -SLAAC is specified in RFC4862_. This method is supported on all physical +SLAAC is specified in :rfc:`4862`. This method is supported on all physical interfaces, and those that are directly connected to a physical interface (ethernet, VLAN, bridge, bond, pseudo-ethernet, wireless). @@ -104,7 +104,7 @@ The command is `set interfaces $type $name ipv6 address autoconf`. Examples: EUI-64 ****** -EUI-64 (64-Bit Extended Unique Identifier) as specified in RFC4291_. IPv6 +EUI-64 (64-Bit Extended Unique Identifier) as specified in :rfc:`4291`. IPv6 addresses in /64 networks can be automatically generated from the prefix and MAC address, if you specify the prefix. @@ -120,7 +120,7 @@ Examples: Router Advertisements ********************* -Router advertisements are described in `RFC4861 section 4.2`_. They are part of what is known as SLAAC (Stateless Address Autoconfiguration). +Router advertisements are described in :rfc:`4861` section 4.2. They are part of what is known as SLAAC (Stateless Address Autoconfiguration). To enable or disable, use: @@ -152,7 +152,7 @@ To set the options described in "Router Advertisement Message Format": **Prefix Information** -Prefix information is described in `RFC4861 section 4.6.2`_ +Prefix information is described in :rfc:`4861` section 4.6.2. .. code-block:: sh @@ -171,8 +171,3 @@ To receive and accept RAs on an interface, you need to enable it with the follow vyos@vyos# set system sysctl custom net.ipv6.conf..accept_ra value 2 - -.. _`RFC4861 section 4.6.2`: https://tools.ietf.org/html/rfc4861#section-4.6.2 -.. _`RFC4861 section 4.2`: https://tools.ietf.org/html/rfc4861#section-4.2 -.. _RFC4862: https://tools.ietf.org/html/rfc4862 -.. _RFC4291: http://tools.ietf.org/html/rfc4291#section-2.5.1 diff --git a/docs/interfaces/l2tpv3.rst b/docs/interfaces/l2tpv3.rst index 4cc296ca..ec2762eb 100644 --- a/docs/interfaces/l2tpv3.rst +++ b/docs/interfaces/l2tpv3.rst @@ -3,7 +3,7 @@ L2TPv3 Interfaces ----------------- -L2TPv3 is a pseudowire protocol, you can read more about here `Wikipedia L2TPv3`_ or `RFC3921`_ +L2TPv3 is a pseudowire protocol, you can read more about here `Wikipedia L2TPv3`_ or :rfc:`3921` L2TPv3 can transport any traffic including ethernet frames. L2TPv2 is limited to PPP. @@ -116,4 +116,3 @@ L2TPv3: set interfaces l2tpv3 l2tpeth0 tunnel-id '10' .. _`Wikipedia L2TPv3`: http://en.wikipedia.org/wiki/L2TPv3 -.. _`RFC3921`: https://tools.ietf.org/html/rfc3931 diff --git a/docs/interfaces/pppoe.rst b/docs/interfaces/pppoe.rst index c4eb2d8f..42d7c3b4 100644 --- a/docs/interfaces/pppoe.rst +++ b/docs/interfaces/pppoe.rst @@ -8,7 +8,7 @@ There are two main ways to setup VyOS to connect over a PPPoE internet connectio **First Method:** (Common for Homes) -In this method, the DSL Modem/Router connects to the ISP for you with your credentials preprogrammed into the device. This gives you an RFC1918_ address, such as 192.168.1.0/24 by default. +In this method, the DSL Modem/Router connects to the ISP for you with your credentials preprogrammed into the device. This gives you an :rfc:`1918` address, such as ``192.168.1.0/24`` by default. For a simple home network using just the ISP's equipment, this is usually desirable. But if you want to run VyOS as your firewall and router, this will result in having a double NAT and firewall setup. This results in a few extra layers of complexity, particularly if you use some NAT or tunnel features. @@ -78,5 +78,3 @@ This command shows the same log as without the 'tail' option but only starts wit .. code-block:: sh show interfaces pppoe 0 log tail - -.. _RFC1918: https://tools.ietf.org/html/rfc1918 diff --git a/docs/interfaces/tunnel.rst b/docs/interfaces/tunnel.rst index 7103e5a2..54e9c1c1 100644 --- a/docs/interfaces/tunnel.rst +++ b/docs/interfaces/tunnel.rst @@ -13,7 +13,7 @@ All those protocols are grouped under 'interfaces tunnel' in VyOS. Let's take a IPIP ---- -This is one of the simplest types of tunnels, as defined by RFC2003_. +This is one of the simplest types of tunnels, as defined by :rfc:`2003`. It takes an IPv4 packet and sends it as a payload of another IPv4 packet. For this reason, there are no other configuration options for this kind of tunnel. An example: @@ -28,7 +28,7 @@ An example: IP6IP6 ------ -This is the IPv6 counterpart of IPIP. I'm not aware of an RFC that defines this encapsulation specifically, but it's a natural specific case of IPv6 encapsulation mechanisms described in RFC2473_. +This is the IPv6 counterpart of IPIP. I'm not aware of an RFC that defines this encapsulation specifically, but it's a natural specific case of IPv6 encapsulation mechanisms described in :rfc:2473`. It's not likely that anyone will need it any time soon, but it does exist. @@ -61,7 +61,7 @@ An example: ---------- -6in4 uses tunneling to encapsulate IPv6 traffic over IPv4 links as defined in RFC4213_. +6in4 uses tunneling to encapsulate IPv6 traffic over IPv4 links as defined in :rfc:`4213`. The 6in4 traffic is sent over IPv4 inside IPv4 packets whose IP headers have the IP protocol number set to 41. This protocol number is specifically designated for IPv6 encapsulation, the IPv4 packet header is immediately followed by the IPv6 packet being carried. The encapsulation overhead is the size of the IPv4 header of 20 bytes, therefore with an MTU of 1500 bytes, IPv6 packets of 1480 bytes can be sent without fragmentation. This tunneling technique is frequently used by IPv6 tunnel brokers like `Hurricane Electric`_. @@ -188,9 +188,5 @@ Results in: description "Description" } - -.. _RFC2003: https://tools.ietf.org/html/rfc2003 -.. _RFC2473: https://tools.ietf.org/html/rfc2473 .. _`other proposals`: https://www.isc.org/downloads/aftr -.. _RFC4213: https://tools.ietf.org/html/rfc4213 .. _`Hurricane Electric`: https://tunnelbroker.net/ diff --git a/docs/interfaces/vxlan.rst b/docs/interfaces/vxlan.rst index 2795fc75..d432bdc6 100644 --- a/docs/interfaces/vxlan.rst +++ b/docs/interfaces/vxlan.rst @@ -1,8 +1,7 @@ VXLAN ----- -VXLAN is an overlaying Ethernet over IP protocol. -It is described in RFC7348_. +VXLAN is an overlaying Ethernet over IP protocol, it's described in :rfc:`7348`. If configuring VXLAN in a VyOS virtual machine, ensure that MAC spoofing (Hyper-V) or Forged Transmits (ESX) are permitted, otherwise forwarded frames @@ -300,8 +299,3 @@ Let's change the Multicast example from above: The default port udp is set to 8472. It can be changed with ``set interface vxlan remote-port `` - - -.. target-notes:: - -.. _RFC7348: https://datatracker.ietf.org/doc/rfc7348/ diff --git a/docs/nat.rst b/docs/nat.rst index d20995d4..1c9408b9 100644 --- a/docs/nat.rst +++ b/docs/nat.rst @@ -266,11 +266,11 @@ one external interface: Firewall rules are written as normal, using the internal IP address as the source of outbound rules and the destination of inbound rules. -NPTv6 (RFC6296) ---------------- +NPTv6 +----- NPTv6 stands for Network Prefix Translation. It's a form of NAT for IPv6. It's -described in RFC6296_. NPTv6 is supported in linux kernel since version 3.13. +described in :rfc:`6296`. NPTv6 is supported in linux kernel since version 3.13. Usage ^^^^^ @@ -469,7 +469,4 @@ Start by checking for IPSec SAs (Security Associations) with: That looks good - we defined 2 tunnels and they're both up and running. - - -.. _RFC6296: https://tools.ietf.org/html/rfc6296 .. _ULAs: http://en.wikipedia.org/wiki/Unique_local_address diff --git a/docs/qos.rst b/docs/qos.rst index adf59108..f1c6a96c 100644 --- a/docs/qos.rst +++ b/docs/qos.rst @@ -664,7 +664,7 @@ In principle, values must be :code:`min-threshold` < :code:`max-threshold` < Possible values for WRED parameters: * precedence - IP precedence, first three bits of the ToS field as defined in - RFC791_. + :rfc:`791`. +------------+----------------------+ | Precedence | Priority | @@ -1027,7 +1027,7 @@ Traffic classes :code:`set traffic-policy shaper class set-dscp ` - DSCP values as per RFC2474_ and RFC4595_: + DSCP values as per :rfc:`2474` and :rfc:`4595`: +---------+------------+--------+------------------------------+ | Binary | Configured | Drop | Description | @@ -1407,9 +1407,6 @@ vif set interfaces ethernet eth1 traffic-policy out 'LAN-OUT' .. _tc: http://en.wikipedia.org/wiki/Tc_(Linux) -.. _RFC791: https://tools.ietf.org/html/rfc791 .. _TBF: https://en.wikipedia.org/wiki/Token_bucket -.. _RFC2474: https://tools.ietf.org/html/rfc2474#page-7 -.. _RFC4595: https://tools.ietf.org/html/rfc4594#page-19 .. _HFSC: https://en.wikipedia.org/wiki/Hierarchical_fair-service_curve .. _IFB: http://www.linuxfoundation.org/collaborate/workgroups/networking/ifb diff --git a/docs/routing/static.rst b/docs/routing/static.rst index 4faa2451..b2c7833a 100644 --- a/docs/routing/static.rst +++ b/docs/routing/static.rst @@ -13,7 +13,7 @@ not make use of DHCP or dynamic routing protocols: set protocols static route 0.0.0.0/0 next-hop 10.1.1.1 distance '1' Another common use of static routes is to blackhole (drop) traffic. In the -example below, RFC1918_ networks are set as blackhole routes. +example below, :rfc:`1918` networks are set as blackhole routes. This prevents these networks leaking out public interfaces, but it does not prevent them from being used as the most specific route has the highest priority. @@ -26,5 +26,3 @@ them from being used as the most specific route has the highest priority. .. note:: Routes with a distance of 255 are effectively disabled and not installed into the kernel. - -.. _RFC1918: https://tools.ietf.org/html/rfc1918 diff --git a/docs/services/dynamic-dns.rst b/docs/services/dynamic-dns.rst index 67de6471..0a9900ed 100644 --- a/docs/services/dynamic-dns.rst +++ b/docs/services/dynamic-dns.rst @@ -6,7 +6,7 @@ address. In order to do so, VyOS includes ddclient_, a perl script written for this exact purpose. ddclient_ uses two methods to update a DNS record. The first one will send -updates directly to the DNS daemon, in compliance with RFC2136_. The second +updates directly to the DNS daemon, in compliance with :rfc:`2136`. The second one involves a third party service, like DynDNS.com or any other similar website. This method uses HTTP requests to transmit the new IP address. You can configure both in VyOS. @@ -14,7 +14,7 @@ can configure both in VyOS. VyOS CLI and RFC2136 ^^^^^^^^^^^^^^^^^^^^ -First, create an RFC2136_ config node : +First, create an :rfc:`2136` config node : .. code-block:: sh @@ -148,5 +148,4 @@ ddclient_ will load the webpage at `[url]` and will try to extract an IP address for the response. ddclient_ will skip any address located before the string set in `[skip]`. - .. include:: references.rst diff --git a/docs/services/lldp.rst b/docs/services/lldp.rst index 37214506..3f22af08 100644 --- a/docs/services/lldp.rst +++ b/docs/services/lldp.rst @@ -17,7 +17,7 @@ Information gathered Information gathered with LLDP is stored in the device as a management information database (MIB_) and can be queried with the Simple Network -Management Protocol (SNMP_) as specified in RFC 2922. The topology of an +Management Protocol (SNMP_) as specified in :rfc:`2922`. The topology of an LLDP-enabled network can be discovered by crawling the hosts and querying this database. Information that may be retrieved include: diff --git a/docs/services/references.rst b/docs/services/references.rst index 257ffe11..408d5288 100644 --- a/docs/services/references.rst +++ b/docs/services/references.rst @@ -2,7 +2,6 @@ .. _ddclient: http://sourceforge.net/p/ddclient/wiki/Home/ .. _`Foundry Discovery Protocol`: https://en.wikipedia.org/wiki/Foundry_Discovery_Protocol .. _MIB: https://en.wikipedia.org/wiki/Management_information_base -.. _RFC2136: https://www.ietf.org/rfc/rfc2136.txt .. _SNMP: https://en.wikipedia.org/wiki/Simple_Network_Management_Protocol .. _SNMPv2: https://en.wikipedia.org/wiki/Simple_Network_Management_Protocol#Version_2 .. _SNMPv3: https://en.wikipedia.org/wiki/Simple_Network_Management_Protocol#Version_3 diff --git a/docs/vpn/dmvpn.rst b/docs/vpn/dmvpn.rst index e53a013a..03bc48ed 100644 --- a/docs/vpn/dmvpn.rst +++ b/docs/vpn/dmvpn.rst @@ -9,9 +9,9 @@ DMVPN is a dynamic VPN technology originally developed by Cisco. While their implementation was somewhat proprietary, the underlying technologies are actually standards based. The three technologies are: -* **NHRP** - NBMA Next Hop Resolution Protocol RFC2332_ -* **mGRE** - Multipoint Generic Routing Encapsulation / mGRE RFC1702_ -* **IPSec** - IP Security (too many RFCs to list, but start with RFC4301_) +* **NHRP** - NBMA Next Hop Resolution Protocol :rfc:`2332` +* **mGRE** - Multipoint Generic Routing Encapsulation / mGRE :rfc:`1702` +* **IPSec** - IP Security (too many RFCs to list, but start with :rfc:`4301`) NHRP provides the dynamic tunnel endpoint discovery mechanism (endpoint registration, and endpoint discovery/lookup), mGRE provides the tunnel @@ -413,8 +413,3 @@ SPOKE2 Example Configuration set protocols static route 192.168.1.0/24 next-hop 10.0.0.1 set protocols static route 192.168.2.0/24 next-hop 10.0.0.2 - - -.. _RFC2332: https://tools.ietf.org/html/rfc2332 -.. _RFC1702: https://tools.ietf.org/html/rfc1702 -.. _RFC4301: https://tools.ietf.org/html/rfc4301 diff --git a/docs/vpn/references.rst b/docs/vpn/references.rst index 49b65cb0..be3d5921 100644 --- a/docs/vpn/references.rst +++ b/docs/vpn/references.rst @@ -4,7 +4,4 @@ .. _RADIUS: https://en.wikipedia.org/wiki/RADIUS .. _FreeRADIUS: https://freeradius.org .. _`Network Policy Server`: https://en.wikipedia.org/wiki/Network_Policy_Server -.. _RFC2332: https://tools.ietf.org/html/rfc2332 -.. _RFC1702: https://tools.ietf.org/html/rfc1702 -.. _RFC4301: https://tools.ietf.org/html/rfc4301 .. _PPTP: https://en.wikipedia.org/wiki/Point-to-Point_Tunneling_Protocol diff --git a/docs/vpn/site2site_ipsec.rst b/docs/vpn/site2site_ipsec.rst index ac410d52..8e0f257b 100644 --- a/docs/vpn/site2site_ipsec.rst +++ b/docs/vpn/site2site_ipsec.rst @@ -225,8 +225,9 @@ Imagine the following topology IPSec IKEv2 site2site VPN (source ./draw.io/vpn_s2s_ikev2.drawio) -.. note:: Don't get confused about the used /31 tunnel subnet. RFC3031_ gives - you additional information for using /31 subnets on point-to-point links. +.. note:: Don't get confused about the used /31 tunnel subnet. :rfc:`3031` + gives you additional information for using /31 subnets on point-to-point + links. **left** @@ -295,5 +296,3 @@ Imagine the following topology set vpn ipsec site-to-site peer 172.18.201.10 local-address '172.18.202.10' set vpn ipsec site-to-site peer 172.18.201.10 vti bind 'vti10' set vpn ipsec site-to-site peer 172.18.201.10 vti esp-group 'ESP_DEFAULT' - -.. _RFC3031: https://tools.ietf.org/html/rfc3021 -- cgit v1.2.3