11 files changed, 127 insertions, 49 deletions
diff --git a/docs/configuration-overview.rst b/docs/configuration-overview.rst
index bd1ab8d8..5bd80028 100644
--- a/docs/configuration-overview.rst
+++ b/docs/configuration-overview.rst
@@ -117,7 +117,7 @@ to enter configuration mode enter the command `configure` when in operational mo
 
   vyos@vyos$ configure
   [edit]
-  cyos@vyos#
+  vyos@vyos#
 
 .. note:: When going into configuration mode, prompt changes from *$* to *#*. To exit configuration mode, type `exit`.
 
@@ -292,8 +292,8 @@ configuration revisions in configuration mode, use the compare command:
   [edit]
   vyos@vyos#
 
-You can rollback configuration using the rollback command, however this
-command will currently trigger a system reboot.
+You can rollback configuration using the rollback command.  This 
+command will apply the selected revision and trigger a system reboot.
 
 .. code-block:: sh
 
@@ -328,8 +328,9 @@ or TFTP.
 Operational info from config mode
 ---------------------------------
 
-When inside configuration mode you are not directly able to execute operational commands,
-access to these commands are possible trough the use of the `run [command]` command.
+When inside configuration mode you are not directly able to execute operational commands.
+
+Access to these commands are possible through the use of the `run [command]` command.
 From this command you will have access to everything accessible from operational mode.
 Command completion and syntax help with `?` and `[tab]` will also work.
 
@@ -353,7 +354,8 @@ This feature was available in Vyatta Core since 6.3
 Local archive and revisions
 ---------------------------
 
-Revisions are stored on disk, you can view them, compare them, and rollback to previous revisions if anything goes wrong.
+Revisions are stored on disk. You can view them, compare them, and rollback to previous revisions if anything goes wrong.
+
 To view existing revisions, use `show system commit` operational mode command.
 
 .. code-block:: sh
@@ -398,4 +400,22 @@ Remote archive
 
 VyOS can copy the config to a remote location after each commit. TFTP, FTP, and SFTP servers are supported.
 
+
+You can specify the location with: 
+
+* `set system config-management commit-archive location URL` 
+
+For example, `set system config-management commit-archive location tftp://10.0.0.1/vyos`.
+
 You can specify the location with `set system config-management commit-archive location URL` command, e.g. `set system config-management commit-archive location tftp://10.0.0.1/vyos`.
+
+Wipe config and restore default
+-------------------------------
+
+In the case you want to completely delete your configuration and restore the default one, you can enter the following command in configuration mode:
+
+.. code-block:: sh
+
+  load /opt/vyatta/etc/config.boot.default
+
+.. note:: If you are remotely connected, you will lose your connection. You may want to copy first the config, edit it to ensure connectivity, and load the edited config.
diff --git a/docs/interfaces/ethernet.rst b/docs/interfaces/ethernet.rst
index 8ef002f8..075b3836 100644
--- a/docs/interfaces/ethernet.rst
+++ b/docs/interfaces/ethernet.rst
@@ -28,10 +28,12 @@ Resulting in:
       speed auto
   }
 
-In addition, Ethernet interfaces provide the extended operational commands
-`show interfaces ethernet <name> physical` and
-`show interfaces ethernet <name> statistics`. Statistics available are driver
-dependent.
+In addition, Ethernet interfaces provide the extended operational commands:
+
+* `show interfaces ethernet <name> physical`
+* `show interfaces ethernet <name> statistics` 
+
+Statistics available are driver dependent.
 
 .. code-block:: sh
 
diff --git a/docs/interfaces/pppoe.rst b/docs/interfaces/pppoe.rst
index 883a3c5d..c4eb2d8f 100644
--- a/docs/interfaces/pppoe.rst
+++ b/docs/interfaces/pppoe.rst
@@ -8,8 +8,9 @@ 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 DSL ISP for you with your credentials preprogrammed into the device and it gives you a local IP address such as 192.168.1.0/24 be default.
-For home networks this is usually fine and saves you trouble but if you want to run a configuration of your own controlled by VyOS, this would mean a Double Firewall, a Double NAT, and double Router as both the DSL Modem/Router and the VyOS would act as firewalls, NATs, and Routers and if you try to do more then just browse Web Sites this will usually cause you trouble.
+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.
+
+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.
 
 **Second Method:** (Common for Businesses)
 
@@ -77,3 +78,5 @@ 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 f466a714..7103e5a2 100644
--- a/docs/interfaces/tunnel.rst
+++ b/docs/interfaces/tunnel.rst
@@ -13,8 +13,8 @@ All those protocols are grouped under 'interfaces tunnel' in VyOS. Let's take a
 IPIP
 ----
 
-This is the simplest tunneling protocol in existence. It is defined by RFC2003_.
-It simply takes an IPv4 packet and sends it as a payload of another IPv4 packet. For this reason it doesn't really have any configuration options by itself.
+This is one of the simplest types of tunnels, as defined by RFC2003_.
+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:
 
@@ -64,7 +64,7 @@ An example:
 6in4 uses tunneling to encapsulate IPv6 traffic over IPv4 links as defined in RFC4213_.
 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.
-qThe 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`_.
+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`_. 
 
 An example:
 
@@ -75,6 +75,8 @@ An example:
   set interfaces tunnel tun0 remote-ip 192.0.2.20
   set interfaces tunnel tun0 address 2001:db8:bb::1/64
 
+A full example of a Tunnelbroker.net config can be found at :ref:`here <examples-tunnelbroker-ipv6>`.
+
 Generic Routing Encapsulation (GRE)
 -----------------------------------
 
@@ -191,4 +193,4 @@ Results in:
 .. _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/
-\ No newline at end of file
+.. _`Hurricane Electric`: https://tunnelbroker.net/
diff --git a/docs/quick-start.rst b/docs/quick-start.rst
index 226c81d0..ebe4d402 100644
--- a/docs/quick-start.rst
+++ b/docs/quick-start.rst
@@ -28,15 +28,10 @@ Enable SSH for remote management:
 
   set service ssh port '22'
 
-Configure Source NAT for our "Inside" network.
-
-.. code-block:: sh
 
-  set nat source rule 100 outbound-interface 'eth0'
-  set nat source rule 100 source address '192.168.0.0/24'
-  set nat source rule 100 translation address masquerade
 
-Configure a DHCP Server:
+Configure DHCP Server and DNS
+^^^^^^^^^^^^^^^^^^^^^^^
 
 .. code-block:: sh
 
@@ -49,17 +44,27 @@ Configure a DHCP Server:
 
 And a DNS forwarder:
 
-Please note that the `listen-on` statement is deprecated. Please use
-`listen-address` instead!
-
 .. code-block:: sh
 
   set service dns forwarding cache-size '0'
-  set service dns forwarding listen-on 'eth1'
+  set service dns forwarding listen-address '192.168.0.1'
   set service dns forwarding name-server '8.8.8.8'
   set service dns forwarding name-server '8.8.4.4'
 
-Add a set of firewall policies for our "Outside" interface:
+NAT and Firewall
+^^^^^^^^^^^^^^^^
+
+Configure Source NAT for our "Inside" network.
+
+.. code-block:: sh
+
+  set nat source rule 100 outbound-interface 'eth0'
+  set nat source rule 100 source address '192.168.0.0/24'
+  set nat source rule 100 translation address masquerade
+
+Add a set of firewall policies for our "Outside" interface.  
+
+This configuration creates a proper stateful firewall that blocks all traffic:
 
 .. code-block:: sh
 
@@ -75,6 +80,13 @@ Add a set of firewall policies for our "Outside" interface:
   set firewall name OUTSIDE-LOCAL rule 20 icmp type-name 'echo-request'
   set firewall name OUTSIDE-LOCAL rule 20 protocol 'icmp'
   set firewall name OUTSIDE-LOCAL rule 20 state new 'enable'
+
+If you wanted to enable SSH access to your firewall from the the Internet, you could create some additional rules to allow the traffic.
+
+These rules allow SSH traffic and rate limit it to 4 requests per minute. This blocks brute-forcing attempts:
+
+.. code-block:: sh
+
   set firewall name OUTSIDE-LOCAL rule 30 action 'drop'
   set firewall name OUTSIDE-LOCAL rule 30 destination port '22'
   set firewall name OUTSIDE-LOCAL rule 30 protocol 'tcp'
@@ -105,7 +117,7 @@ Commit changes, save the configuration, and exit configuration mode:
   vyos@vyos$
 
 Basic QoS
----------
+^^^^^^^^^
 
 The traffic policy subsystem provides an interface to Linux traffic control
 (tc_).
@@ -163,4 +175,38 @@ VyOS 1.2 (Crux) also supports HFSC (:code:`set traffic-policy shaper-hfsc`)
 
 See further information in the :ref:`qos` chapter.
 
+Security Hardening
+^^^^^^^^^^^^^^^^^^
+
+Especially if you are allowing SSH access from the Internet, there are a few additional configuration steps that should be taken.
+
+Create a user to replace the default `vyos` user:
+
+.. code-block:: sh
+
+  set system login user myvyosuser level admin
+  set system login user myvyosuser authentication plaintext-password mysecurepassword
+
+Set up SSH key based authentication.  For example, on Linux you'd want to run `ssh-keygen -t rsa`.  Then the contents of `id_rsa.pub` would be used below:
+
+.. code-block:: sh
+
+  set system login user myvyosuser authentication public-keys myusername@mydesktop type ssh-rsa
+  set system login user myvyosuser authentication public-keys myusername@mydesktop key contents_of_id_rsa.pub
+
+Or you can use the `loadkey` command. Commit and save.
+
+Finally, try and ssh into the VyOS install as your new user.  
+
+Once you have confirmed that your new user can access your server, without a password, delete the original `vyos` user and disable password authentication into SSH:
+
+.. code-block:: sh
+
+  delete system login user vyos
+  set service ssh disable-password-authentication
+
+Commit and save.
+
+
+
 .. _tc: http://en.wikipedia.org/wiki/Tc_(Linux)
diff --git a/docs/routing/index.rst b/docs/routing/index.rst
index 376e0919..1a1db43f 100644
--- a/docs/routing/index.rst
+++ b/docs/routing/index.rst
@@ -8,8 +8,7 @@ policy routing, and dynamic routing using standard protocols (RIP, OSPF, and
 BGP).
 
 .. toctree::
-   :maxdepth: 2
-   :hidden:
+   :maxdepth: 1
 
    arp
    bgp
diff --git a/docs/routing/pbr.rst b/docs/routing/pbr.rst
index a8ee9e87..62dfcaec 100644
--- a/docs/routing/pbr.rst
+++ b/docs/routing/pbr.rst
@@ -73,9 +73,9 @@ Add policy route matching VLAN source addresses
   set policy route PBR rule 20 description 'Route VLAN10 traffic to table 10'
   set policy route PBR rule 20 source address '192.168.188.0/24'
 
-  set policy route PBR rule 20 set table '11'
-  set policy route PBR rule 20 description 'Route VLAN11 traffic to table 11'
-  set policy route PBR rule 20 source address '192.168.189.0/24'
+  set policy route PBR rule 30 set table '11'
+  set policy route PBR rule 30 description 'Route VLAN11 traffic to table 11'
+  set policy route PBR rule 30 source address '192.168.189.0/24'
 
 Apply routing policy to **inbound** direction of out VLAN interfaces
 
diff --git a/docs/routing/static.rst b/docs/routing/static.rst
index e1f96c31..4faa2451 100644
--- a/docs/routing/static.rst
+++ b/docs/routing/static.rst
@@ -13,11 +13,10 @@ 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, RFC 1918 private IP networks are set as blackhole routes. This
-does not prevent networks within these segments from being used, since the
-most specific route is always used. It does, however, prevent traffic to
-unknown private networks from leaving the router. Commonly refereed to as
-leaking.
+example below, RFC1918_ 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.
 
 .. code-block:: sh
 
@@ -27,3 +26,5 @@ leaking.
 
 .. 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/dns-forwarding.rst b/docs/services/dns-forwarding.rst
index a8501c8f..067dacaf 100644
--- a/docs/services/dns-forwarding.rst
+++ b/docs/services/dns-forwarding.rst
@@ -32,22 +32,26 @@ Setting a forwarding DNS server for a specific domain:
 Example 1
 ^^^^^^^^^
 
-Router with two interfaces eth0 (WAN link) and eth1 (LAN). A DNS server for the
-local domain (example.com) is at 192.0.2.1, other DNS requests are forwarded
-to Google's DNS servers.
+Router with two interfaces eth0 (WAN link) and eth1 (LAN). Split DNS for example.com.
+
+* DNS request for a local domain (example.com) get forwarded to 192.0.2.1
+* Other DNS requests are forwarded to Google's DNS servers.
+* The IP address for the LAN interface is 192.168.0.1.
 
 .. code-block:: sh
 
   set service dns forwarding domain example.com server 192.0.2.1
   set service dns forwarding name-server 8.8.8.8
   set service dns forwarding name-server 8.8.4.4
-  set service dns forwarding listen-on 'eth1'
+  set service dns forwarding listen-address 192.168.0.1
 
 Example 2
 ^^^^^^^^^
 
 Same as example 1 but with additional IPv6 addresses for Google's public DNS
-servers:
+servers.
+
+The IP addresses for the LAN interface are 192.168.0.1 and 2001:db8::1
 
 .. code-block:: sh
 
@@ -56,4 +60,5 @@ servers:
   set service dns forwarding name-server 8.8.4.4
   set service dns forwarding name-server 2001:4860:4860::8888
   set service dns forwarding name-server 2001:4860:4860::8844
-  set service dns forwarding listen-on 'eth1'
+  set service dns forwarding listen-address 2001:db8::1
+  set service dns forwarding listen-address 192.168.0.1 
diff --git a/docs/services/index.rst b/docs/services/index.rst
index 03fdc9c4..8f7553a8 100644
--- a/docs/services/index.rst
+++ b/docs/services/index.rst
@@ -8,7 +8,7 @@ Services
 This chapter descriptes the available system/network services provided by VyOS.
 
 .. toctree::
-   :hidden:
+   :maxdepth: 1
 
    conntrack
    dhcp
diff --git a/docs/system/host-information.rst b/docs/system/host-information.rst
index f50585aa..788f7bcc 100644
--- a/docs/system/host-information.rst
+++ b/docs/system/host-information.rst
@@ -51,8 +51,8 @@ Example: Set system hostname to 'RT01':
 Domain Name
 ^^^^^^^^^^^
 
-A domainname is the label (name) assigned to a computer network and is thus
-unique!
+A domain name is the label (name) assigned to a computer network and is thus
+unique.
 
 Set the system's domain:
 
@@ -158,7 +158,7 @@ It is replaced by inserting a static route into the routing table using:
 
   set protocols static route 0.0.0.0/0 next-hop <gateway ip>
 
-Delete default route fomr the system
+Delete the default route from the system
 
 .. code-block:: sh