13 files changed, 78 insertions, 68 deletions
diff --git a/docs/apxA-troubleshooting.rst b/docs/apxA-troubleshooting.rst
index a5a6a72c..917dc1b7 100644
--- a/docs/apxA-troubleshooting.rst
+++ b/docs/apxA-troubleshooting.rst
@@ -76,8 +76,8 @@ into a single tool. An example of its output is shown:
   3. 10.62.255.71                  0.0%    34    1.4   1.4   1.3   2.0   0.1
   4. 10.62.212.12                  0.0%    34    1.6   1.6   1.6   1.7   0.0
 
-**NOTE:** The output of '''mtr''' consumes the screen and will replace your
-command prompt.
+.. note:: The output of ``mtr`` consumes the screen and will replace your
+   command prompt.
 
 Several options are available for changing the display output. Press `h` to
 invoke the built in help system. To quit, just press `q` and you'll be returned
diff --git a/docs/ch01-install.rst b/docs/ch01-install.rst
index 1751deb0..b1896ef6 100644
--- a/docs/ch01-install.rst
+++ b/docs/ch01-install.rst
@@ -28,13 +28,14 @@ version if something breaks after upgrade. Every version is contained in its
 own squashfs image that is mounted in a union filesystem together with a
 directory for mutable data (configs etc.).
 
-**NOTE:** older versions used to support non-image installation (`install
-system` command). It's been deprecated since the time image installation was
-introduced (long before the fork), and does not provide any version management
-capabilities. You **should not** use it for new installations even if it's still
-available in new versions. You should not worry about older systems installed
-that way though, they can be upgraded with "add system image". In addition the
-`install system` command has been removed in VyOS 1.2 (Crux).
+.. note:: Older versions used to support non-image installation (`install
+   system` command). It's been deprecated since the time image installation
+   was introduced (long before the fork), and does not provide any version
+   management capabilities. You **should not** use it for new installations
+   even if it's still available in new versions. You should not worry about
+   older systems installed that way though, they can be upgraded with ``add
+   system image``. In addition the ``install system`` command has been
+   removed in VyOS 1.2 (Crux).
 
 To install VyOS, run ``install image``.
 
diff --git a/docs/ch02-cli.rst b/docs/ch02-cli.rst
index 7023c263..da93dcd8 100644
--- a/docs/ch02-cli.rst
+++ b/docs/ch02-cli.rst
@@ -72,8 +72,7 @@ To enter configuration mode use the `configure` command:
   [edit]
   vyos@vyos:~#
 
-Note that the prompt changes from `$` to `#`. To exit configuration mode, type
-`exit`.
+.. note:: Prompt changes from `$` to `#`. To exit configuration mode, type `exit`.
 
 .. code-block:: sh
 
diff --git a/docs/ch03-quick-start.rst b/docs/ch03-quick-start.rst
index 11912947..3a4773b6 100644
--- a/docs/ch03-quick-start.rst
+++ b/docs/ch03-quick-start.rst
@@ -154,8 +154,8 @@ interface-level traffic-policy directive:
   set interfaces ethernet eth0 traffic-policy out 'WAN-OUT'
   set interfaces ethernet eth1 traffic-policy out 'LAN-OUT'
 
-Note that a traffic policy can also be defined to match specific traffic
-flows using class statements.
+.. note:: A traffic policy can also be defined to match specific traffic
+   flows using class statements.
 
 VyOS 1.2 (Crux) also supports HFSC (:code:`set traffic-policy shaper-hfsc`)
 
diff --git a/docs/ch05-network-interfaces.rst b/docs/ch05-network-interfaces.rst
index fb1aba3e..2e2a9ee5 100644
--- a/docs/ch05-network-interfaces.rst
+++ b/docs/ch05-network-interfaces.rst
@@ -139,8 +139,8 @@ The command is `set interfaces $type $name ipv6 address autoconf`. Examples:
   set interfaces ethernet eth0 vif 90 ipv6 address autoconf
   set interfaces bridge br0 ipv6 address autoconf
 
-**NOTE:** This method automatically disables IPv6 traffic forwarding on the
-interface in question.
+.. note:: This method automatically disables IPv6 traffic forwarding on the
+   interface in question.
 
 EUI-64
 ******
@@ -314,8 +314,8 @@ Example Result:
 In addition to normal IP interface configuration, bridge interfaces support
 Spanning-Tree Protocol. STP is disabled by default.
 
-**NOTE:** Please use caution when introducing spanning-tree protocol on a
-network as it may result in topology changes.
+.. note:: Please use caution when introducing spanning-tree protocol on a
+   network as it may result in topology changes.
 
 To enable spanning-tree use the `set interfaces bridge <name> stp true` command:
 
diff --git a/docs/ch06-routing.rst b/docs/ch06-routing.rst
index 165cb99f..5efe6442 100644
--- a/docs/ch06-routing.rst
+++ b/docs/ch06-routing.rst
@@ -30,8 +30,8 @@ leaking.
   set protocols static route 172.16.0.0/12 blackhole distance '254'
   set protocols static route 192.168.0.0/16 blackhole distance '254'
 
-Note that routes with a distance of 255 are effectively disabled and not
-installed into the kernel.
+.. note:: Routes with a distance of 255 are effectively disabled and not
+   installed into the kernel.
 
 RIP
 ---
diff --git a/docs/ch07-firewall.rst b/docs/ch07-firewall.rst
index 8fe6dcfe..397c31ac 100644
--- a/docs/ch07-firewall.rst
+++ b/docs/ch07-firewall.rst
@@ -32,8 +32,9 @@ Groups
 Firewall groups represent collections of IP addresses, networks, or ports. Once
 created, a group can be referenced by firewall rules as either a source or
 destination. Members can be added or removed from a group without changes to
-or the need to reload individual firewall rules.  Note that groups can also
-be referenced by NAT configuration.
+or the need to reload individual firewall rules.
+
+.. note:: Groups can also be referenced by NAT configuration.
 
 While network groups accept IP networks in CIDR notation, specific IP addresses
 can be added as a 32-bit prefix. If you foresee the need to add a mix of
@@ -81,9 +82,10 @@ Example of a rule-set to filter traffic to the internal network:
 Applying a Rule-Set to an Interface
 -----------------------------------
 
-Once a rule-set is created, it can be applied to an interface. Note only one
-rule-set can be applied to each interface for `in`, `out`, or `local` traffic
-for each protocol (IPv4 and IPv6).
+Once a rule-set is created, it can be applied to an interface.
+
+.. note:: Only one rule-set can be applied to each interface for `in`, `out`,
+   or `local` traffic for each protocol (IPv4 and IPv6).
 
 .. code-block:: sh
 
diff --git a/docs/ch08-nat.rst b/docs/ch08-nat.rst
index 9b7f9c34..df0b61af 100644
--- a/docs/ch08-nat.rst
+++ b/docs/ch08-nat.rst
@@ -57,7 +57,7 @@ rule [n] translation address` statement.
 
   set nat source rule 100 translation address '203.0.113.32-203.0.113.63'
 
-**NOTE:** Avoiding "leaky" NAT
+.. note:: Avoiding "leaky" NAT
 
 Linux netfilter will not NAT traffic marked as INVALID. This often confuses
 people into thinking that Linux (or specifically VyOS) has a broken NAT
@@ -82,7 +82,7 @@ protocol behavior. For this reason, VyOS does not globally drop invalid state
 traffic, instead allowing the operator to make the determination on how the
 traffic is handled.
 
-**NOTE:** Avoiding NAT breakage in the absence of split-DNS
+.. note:: Avoiding NAT breakage in the absence of split-DNS
 
 A typical problem with using NAT and hosting public servers is the ability for
 internal systems to reach an internal server using it's external IP address.
@@ -175,9 +175,9 @@ Which would generate the following NAT destination configuration:
       }
   }
 
-Note that if forwarding traffic to a different port than it is arriving on,
-you may also configure the translation port using `set nat destination rule
-[n] translation port`.
+.. note:: If forwarding traffic to a different port than it is arriving on,
+   you may also configure the translation port using `set nat destination rule
+   [n] translation port`.
 
 This establishes our Port Forward rule, but if we created a firewall policy it
 will likely block the traffic.
@@ -213,8 +213,10 @@ This would generate the following configuration:
       }
   }
 
-**NOTE**: If you have configured the `INSIDE-OUT` policy, you will need to add
-additional rules to permit inbound NAT traffic.
+.. note::
+
+  If you have configured the `INSIDE-OUT` policy, you will need to add
+  additional rules to permit inbound NAT traffic.
 
 1-to-1 NAT
 ----------
diff --git a/docs/ch09-vpn.rst b/docs/ch09-vpn.rst
index 55e2e24d..1cbe275b 100644
--- a/docs/ch09-vpn.rst
+++ b/docs/ch09-vpn.rst
@@ -204,9 +204,10 @@ installing that route on clients.
 
 Since it's a HQ and branch offices setup, we will want all clients to have
 fixed addresses and we will route traffic to specific subnets through them. We
-need configuration for each client to achieve this. Note that clients are
-identified by the CN field of their x.509 certificates, in this example the CN
-is client0:
+need configuration for each client to achieve this.
+
+.. note:: Clients are identified by the CN field of their x.509 certificates,
+   in this example the CN is ``client0``:
 
 .. code-block:: sh
 
@@ -290,8 +291,8 @@ needed as well.
   set vpn l2tp remote-access dns-servers server-1 '8.8.8.8'
   set vpn l2tp remote-access dns-servers server-2 '8.8.4.4'
 
-**NOTE:** Those are the `Google public DNS`_ servers. You can also use the
-public available servers from Quad9_ (9.9.9.9) or Cloudflare_ (1.1.1.1).
+.. note:: Those are the `Google public DNS`_ servers. You can also use the
+   public available servers from Quad9_ (9.9.9.9) or Cloudflare_ (1.1.1.1).
 
 Established sessions can be viewed using the **show vpn remote-access**
 operational command.
@@ -325,9 +326,9 @@ authentication. This is done using the `radius-server` and `key` nodes:
   set vpn l2tp remote-access authentication radius-server 1.1.1.1 key 'foo'
   set vpn l2tp remote-access authentication radius-server 2.2.2.2 key 'foo'
 
-**NOTE:** Some RADIUS_ severs make use of an access control list who is allowed
-to query the server. Please configure your VyOS router in the allowed client
-list.
+.. note:: Some RADIUS_ severs make use of an access control list who is allowed
+   to query the server. Please configure your VyOS router in the allowed client
+   list.
 
 RADIUS source address
 *********************
@@ -468,9 +469,9 @@ In short, DMVPN provides the capability for creating a dynamic-mesh VPN
 network without having to pre-configure (static) all possible tunnel end-point
 peers.
 
-**NOTE:** DMVPN only automates the tunnel endpoint discovery and setup. A
-complete solution also incorporates the use of a routing protocol. BGP is
-particularly well suited for use with DMVPN.
+.. note:: DMVPN only automates the tunnel endpoint discovery and setup. A
+   complete solution also incorporates the use of a routing protocol. BGP is
+   particularly well suited for use with DMVPN.
 
 Baseline Configuration:
 
diff --git a/docs/ch10-qos.rst b/docs/ch10-qos.rst
index e6346f41..4be68662 100644
--- a/docs/ch10-qos.rst
+++ b/docs/ch10-qos.rst
@@ -1239,9 +1239,10 @@ source
 tcp
 ###
 
-**NOTE:** you must set ip protocol to TCP to use the TCP filters.
-**NOTE#2**: This filter will only match packets with an IPv4 header length of
-20 bytes (which is the majority of IPv4 packets anyway).
+.. note:: You must set ip protocol to TCP to use the TCP filters.
+
+.. note:: This filter will only match packets with an IPv4 header length of
+   20 bytes (which is the majority of IPv4 packets anyway).
 
 .. code-block:: sh
 
@@ -1304,9 +1305,11 @@ source
 tcp
 ###
 
-**NOTE**: you must set ipv6 protocol to TCP to use the TCP filters.
-**NOTE#2**: This filter will only match IPv6 packets with no header extension
-(http://en.wikipedia.org/wiki/IPv6_packet#Extension_headers no header extension).
+.. note:: You must set ipv6 protocol to TCP to use the TCP filters.
+
+.. note:: This filter will only match IPv6 packets with no header extension, see
+   http://en.wikipedia.org/wiki/IPv6_packet#Extension_headers for no header
+   extension.
 
 .. code-block:: sh
 
diff --git a/docs/ch11-services.rst b/docs/ch11-services.rst
index 894e47b2..0bdb4797 100644
--- a/docs/ch11-services.rst
+++ b/docs/ch11-services.rst
@@ -49,7 +49,7 @@ VyOS provides support for DHCP failover:
   set service dhcp-server shared-network-name 'LAN' subnet '192.168.0.0/24' failover name 'foo'
   set service dhcp-server shared-network-name 'LAN' subnet '192.168.0.0/24' failover peer-address '192.168.0.2'
 
-**NOTE:** `name` must be identical on both sides!
+.. note:: `name` must be identical on both sides!
 
 The primary and secondary statements determines whether the server is primary or secondary
 
@@ -63,9 +63,9 @@ or
 
   set service dhcp-server shared-network-name 'LAN' subnet '192.168.0.0/24' failover status 'secondary'
 
-**NOTE:** In order for the primary and the secondary DHCP server to keep their
-lease tables in sync, they must be able to reach each other on TCP port 647.
-If you have firewall rules in effect, adjust them accordingly.
+.. note:: In order for the primary and the secondary DHCP server to keep
+   their lease tables in sync, they must be able to reach each other on TCP
+   port 647. If you have firewall rules in effect, adjust them accordingly.
 
 Static mappings MAC/IP
 ^^^^^^^^^^^^^^^^^^^^^^
@@ -378,8 +378,10 @@ Example 1: Static IPv6 MAC-based mapping
 
 IPv6 address `2001:db8:100::101` shall be statically mapped to a device with
 MAC address `00:15:c5:b7:5e:23`, this host-specific mapping shall be named
-`client1`. **NOTE:** The MAC address identifier is defined by the last 4 byte
-of the MAC address.
+`client1`.
+
+.. note:: The MAC address identifier is defined by the last 4 byte of the
+   MAC address.
 
 .. code-block:: sh
 
@@ -814,8 +816,8 @@ mDNS repeater can be temporarily disabled without deleting the service using
 
   set service mdns repeater disable
 
-**NOTE**: You can not run this in a VRRP setup, if multiple mDNS repeaters are
-launched in a subnet you will experience the mDNS packet storm death!
+.. note:: You can not run this in a VRRP setup, if multiple mDNS repeaters
+   are launched in a subnet you will experience the mDNS packet storm death!
 
 UDP broadcast relay
 -------------------
@@ -864,8 +866,8 @@ configuration by:
 
   set service broadcast-relay disable
 
-**NOTE:** You can run the UDP broadcast relay service on multiple routers
-connected to a subnet. There is **NO** UDP broadcast relay packet storm!
+.. note:: You can run the UDP broadcast relay service on multiple routers
+   connected to a subnet. There is **NO** UDP broadcast relay packet storm!
 
 .. _ddclient: http://sourceforge.net/p/ddclient/wiki/Home/
 .. _RFC2136: https://www.ietf.org/rfc/rfc2136.txt
diff --git a/docs/ch12-system.rst b/docs/ch12-system.rst
index a8d8b520..e613bfac 100644
--- a/docs/ch12-system.rst
+++ b/docs/ch12-system.rst
@@ -29,7 +29,7 @@ Set a system host name:
 
   set system host-name <hostname>
 
-**NOTE:** Only letters, numbers and hyphens are allowed.
+.. note:: Only letters, numbers and hyphens are allowed.
 
 Show host name:
 
@@ -64,7 +64,7 @@ Set the system's domain:
 
   set system domain-name <domain>
 
-**NOTE:** Only letters, numbers, hyphens and periods are allowed.
+.. note:: Only letters, numbers, hyphens and periods are allowed.
 
 Show domain:
 
@@ -235,9 +235,9 @@ The following command will load the public key `dev.pub` for user `jsmith`
 
   loadkey jsmith dev.pub
 
-**NOTE:** This requires uploading the `dev.pub` public key to the VyOS router
-first. As an alternative you can also load the SSH public key directly from a
-remote system:
+.. note:: This requires uploading the `dev.pub` public key to the VyOS router
+   first. As an alternative you can also load the SSH public key directly
+   from a remote system:
 
 .. code-block:: sh
 
diff --git a/docs/ch14-image-mgmt.rst b/docs/ch14-image-mgmt.rst
index 05370d8c..a36ad112 100644
--- a/docs/ch14-image-mgmt.rst
+++ b/docs/ch14-image-mgmt.rst
@@ -92,12 +92,12 @@ configuration.
   We need 344880 KB, but we only have 17480 KB.
   Exiting...
 
-**NOTE #1:** Rolling releases are not GPG signed, only the real release build
-will have a proper GPG signature.
+.. note:: Rolling releases are not GPG signed, only the real release build
+   will have a proper GPG signature.
 
-**NOTE #2:** VyOS configuration is associated to each image, and each image has
-a unique copy of its configuration. This is different than a traditional
-network router where the configuration is shared across all images.
+.. note:: VyOS configuration is associated to each image, and each image has
+   a unique copy of its configuration. This is different than a traditional
+   network router where the configuration is shared across all images.
 
 If you need some files from a previous images - take a look inside a
 :code:`/live` directory.