Add documentation and subnet-get command to yap.

.gitignore

@@ -0,0 +1 @@
+docs/

Makefile

@@ -14,5 +14,12 @@ install:
 	test -f $(DESTDIR)$(TOPFILE) || echo "partner:" > $(DESTDIR)$(TOPFILE)
 	grep -q 'aggregator|vxr' $(DESTDIR)$(TOPFILE) || cat salt/top.sls >> $(DESTDIR)$(TOPFILE)
 
+docs: README.rst
+	mkdir -p docs/
+	cp VXLAN-backhaul.png docs/
+	rst2html README.rst docs/index.html
 
-.PHONY: all install
+clean:
+	rm -rf docs/
+
+.PHONY: all install clean

README.rst

@@ -15,6 +15,10 @@ If a backhaul is not already set up in a data center, additional "VXR" boxes
 can be added to each data center to provide an overlay backhaul using
 VXLAN-over-IPSEC.
 
+.. contents::
+
+Installation and setup
+----------------------
 
 Initial installation
 ====================
@@ -23,6 +27,10 @@ First, install the software on the bondingadmin server::
 
     make install
 
+
+.. note:: The rest of the yap commands are run on the management server, unless
+   otherwise stated.
+
 Then add a read-only user in the Bondingadmin web interface allow the tool to
 query the API. Add the user details using the ``yap`` tool::
 
@@ -38,8 +46,8 @@ spaces. To add a region::
     yap region-add yvr
 
 
-Setting up spaces
+Adding spaces
-=================
+=============
 
 To add the space with key ``foo``::
 
@@ -118,3 +126,217 @@ example, to show the state of space ``foo`` on the VXR ``yvr-vxr01`` and the
 aggregator with ID 1::
 
     salt -C 'L@yvr-vxr01,node-1' cmd.run "yap status foo"
+
+
+Architectural overview
+----------------------
+
+The following diagram shows an overview of the various nodes involved in a
+typical YAP deployment for a space. This fictional space has a firewall in
+YVR only, but bonds in both YVR and TOR.
+
+The red circles denote details and troubleshooting commands that can be run
+on each respective node.
+
+.. image:: VXLAN-backhaul.png
+   :scale: 30 %
+   :alt: VXLAN backhaul diagram
+
+.. This diagram may be updated at the following link:
+   https://www.lucidchart.com/invitations/accept/27dfc950-e351-4511-b42a-d1f08fe26833
+
+
+Adding spaces
+-------------
+
+Prerequisites
+=============
+
+* All bonds are moved to yap-enabled aggregators.
+* A VLAN is designated for each region that will host bonds. For example, for
+  a space that has bonds on aggregators in two regions, YVR and TOR, you must
+  designate a VLAN for both regions.
+
+Migrating existing private WAN spaces
+=====================================
+
+The following commands are all to be run on the management server.
+
+.. warning:: There will be a brief outage when migrating a space.
+
+1. Add the space::
+
+    yap space-add <key>
+
+   This can be run in advance as it does not make any runtime changes.
+
+2. To calculate the subnet for each region/space, you can run the following
+   command. This only returns the network that will be designated for the VLAN
+   on the aggregators in the region, it does not apply any changes::
+
+    yap subnet-get <key> <region>
+
+   This will return the base subnet for this space-region pair, as well as the
+   specific IPs of the aggregators in that region. The first IP in the subnet
+   is reserved for the firewall::
+
+    Subnet: 100.31.88.0/21
+    Firewall: 100.31.88.1
+    Aggregators:
+        agg03: 100.31.88.5
+
+3. Configure the firewall with the IP shown in step 2 on the VLAN interface and
+   configure OSPF. While the exact settings will be vendor-specific, here are
+   the general details:
+
+   * area 0.0.0.0
+   * subnet <from step 2>
+   * redistribute connected
+   * hello interval 10s
+   * dead interval 40s
+
+4. Add a VLAN association for each region::
+
+	yap vlan-set <key> <region> <vlan_id>
+
+   This will start the VLAN interfaces on each yap-enabled aggregator in the
+   region using the same subnet reflected in step 2.
+
+   .. caution:: This is the start of an outage for the space, as the private
+      WAN router's BGP protocols for the space are brought down to prevent
+      routing loops/conflicts.
+
+5. Confirm OSPF is up in each region by running this command on the
+   aggregators::
+
+    yap status <key>
+
+   If the OSPF protocol is not 'Running', jump to troubleshooting
+   `B: Aggregator`_.
+
+6. Once OSPF is up and the routes have propagated both ways, you can disable
+   the outbound gateway configured in the existing space to finish cleanup.
+
+
+Adding new private WAN spaces
+=============================
+
+Follow the same steps as for migrating an existing space, with these two
+exceptions:
+
+* Enable private WAN on the space through the management server interface.
+* An outbound gateway should not be enabled in the space's private WAN tab,
+  however, you may wish to add a disabled gateway for record-keeping of the
+  firewall's IP.
+
+Troubleshooting
+---------------
+
+A: Bond
+=======
+
+While YAP doesn't directly affect bonds, it can be useful to troubleshoot
+private WAN routes at the bond level, by inspecting their routing table::
+
+    ip route show table bonding-pwan
+
+B: Aggregator
+=============
+
+YAP-enabled aggregators have a ``yap`` command installed that can be used
+to show information about the spaces currently running on the aggregator.
+
+The most useful command is ``yap status <space key>``, which shows the status
+of the bird protocols and the current routing table for that space::
+
+    agg:~# yap status bammya
+
+    spcbammya BGP      krt8251  up     2018-12-06  Established
+    ospf_bammya OSPF     krt8251  up     07:21:22    Running
+
+    default via 100.109.152.1 dev vl-bammya proto bird
+    10.10.1.0/24 via 100.109.152.8 dev vl-bammya proto bird
+    192.168.33.0/24 via 100.109.152.8 dev vl-bammya proto bird
+
+The BGP protocol for the space is controlled by bonding and should be in
+'Established' state. The ``ospf_<key>`` protocol is the one managed by YAP and
+should be in 'Running' state. If the status is 'Alone' instead, it means there
+are no OSPF neighbors.
+
+If you want to, you can show the current OSPF neighbors for a space::
+
+    pwanbirdc - show ospf neighbor ospf_<key>
+
+An aggregator has one VLAN interface per space, which follows the naming
+convention of ``vl-<key>``. You can use this command to show the VLAN id::
+
+    ip -d link show dev vl-bammya
+
+Lastly, you can look at the VLAN interface to see the aggregator's IP, as well
+as the subnet designated for the space and routing group::
+
+    agg:~# ip address show dev vl-bammya
+
+    440: vl-bammya@eth1: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc noqueue state UP group default qlen 1000
+        link/ether d0:43:1e:c5:1b:44 brd ff:ff:ff:ff:ff:ff
+        inet 100.109.152.7/21 scope global vl-bammya
+
+In the example above, the firewall would be configured with ``100.109.152.1/21``.
+
+Knowing the subnet, you can test ICMP connectivity to the firewall IP::
+
+    ping <gateway IP>
+
+When troubleshooting OSPF it may be useful to run a packet capture on the VLAN
+interface to see which options are set::
+
+    tcpdump -ni vl-<key> proto 89 -vvv
+
+
+D: VXR
+======
+
+The most useful command is ``yap status <space key>``, which shows the status
+of the bird protocol and the current routing table for that space::
+
+    agg:~# yap status bammya
+
+    ospf_bammya OSPF       bammya up     07:21:23.175  Running
+
+    default via 100.109.152.1 dev vl-bammya proto bird metric 32
+    10.10.1.0/24 via 100.109.152.8 dev vl-bammya proto bird metric 32
+
+Otherwise, the same troubleshooting steps apply as on the aggregator.
+
+If you need to troubleshoot the VXLAN as well, you can view the interface
+details with the standard linux utilities::
+
+    agg:~# ip -d l show dev vx-<key>
+
+    191: vx-bammya: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1432 qdisc noqueue state UNKNOWN mode DEFAULT group default qlen 1000
+        link/ether 66:da:5c:17:37:38 brd ff:ff:ff:ff:ff:ff promiscuity 0
+        vxlan id 59 srcport 0 0 dstport 4789 ageing 300 udpcsum noudp6zerocsumtx noudp6zerocsumrx addrgenmode eui64 numtxqueues 1 numrxqueues 1 gso_max_size 65536 gso_max_segs 65535
+
+E: Firewall
+===========
+
+Out of YAP's control. Here be dragons.
+
+F: bondingadmin
+===============
+
+Like all the nodes, there is a command in the path called ``yap`` that serves
+as the entry point for all things backhauled. Most of the commands are
+described above in their relevant sections. You can always run ``yap`` with
+no arguments to see what actions are available::
+
+	root@bondingadmin:~# yap
+	/usr/local/bin/yap <action> [args]
+
+	Actions:
+
+	region-list
+	region-show <region>
+	region-add <region>
+	...
+

update-docs.sh

@@ -0,0 +1,15 @@
+#!/bin/bash -e
+
+RADOSGW_USER="yap-docs"
+BUCKET_NAME="yap-docs"
+BUCKET="s3://$BUCKET_NAME"
+ACCESS_KEY=$(radosgw-admin user info --uid=$RADOSGW_USER | grep "access_key" | cut -d '"' -f 4)
+SECRET_ACCESS_KEY=$(radosgw-admin user info --uid=$RADOSGW_USER | grep "secret_key" | cut -d '"' -f 4)
+
+S3CMD_OPTIONS="--access_key=$ACCESS_KEY --secret_key=$SECRET_ACCESS_KEY --no-ssl --acl-public --host=rgw.multapplied.net --host-bucket='yap-docs.rgw.multapplied.net'"
+echo "$S3CMD_OPTIONS"
+S3CMD="s3cmd $S3CMD_OPTIONS"
+
+$S3CMD mb $BUCKET
+$S3CMD ws-create $BUCKET
+$S3CMD sync docs/ $BUCKET

yap

@@ -173,6 +173,52 @@ function list_sections() {
 }
 
 
+function ip2dec() {
+    local a b c d ip=$@
+    IFS=. read -r a b c d <<< "$ip"
+    printf '%d\n' "$((a * 256 ** 3 + b * 256 ** 2 + c * 256 + d))"
+}
+
+
+function dec2ip() {
+    local delim ip dec=$@
+    for e in {3..0} ; do
+        ((octet = dec / (256 ** e) ))
+        ((dec -= octet * 256 ** e))
+        ip+=$delim$octet
+        delim=.
+    done
+    printf '%s' "$ip"
+}
+
+
+# Generate an IP for a VLAN interface based on the VLAN and and the YAP ID.
+# The first octet will always be 100, while the other 3 octets are split into
+# 3 sections of varying size to contain the IP type, the VLAN, and the YAP ID:
+#
+#  type: 1-bit
+#  vlan ID: 12-bits
+#  YAP ID: 11-bits
+#
+# The resulting IP should be used with a prefix length of 21
+#
+function get_vlan_ip() {
+    vlan_id=$1
+    yap_id=$2
+
+    # Start at 100.0.0.0
+    local ip=$(ip2dec 100.0.0.0)
+
+    # Add the VLAN ID, shifted 11-bits
+    ((ip += vlan_id << 11))
+
+    # Add the YAP ID
+    ((ip += yap_id))
+
+    dec2ip $ip
+}
+
+
 function validate_ip() {
     if ! [[ $1 =~ ^(0*(1?[0-9]{1,2}|2([0-4][0-9]|5[0-5]))\.){3}0*(1?[0-9]{1,2}|2([‌​0-4][0-9]|5[0-5]))$ ]] ; then
         return 1
@@ -453,9 +499,10 @@ function region_show() {
     echo "VLAN associations:"
 
     for space in $(list_sections "/regions/$region/spaces") ; do
-        var="/regions/$region/spaces/$space/vlan"
+        var="$space/vlan"
         if has_var "$var" ; then
-            echo "    $(basename space) $(get_var $var)"
+            vlan_id=$(get_var $var)
+            echo "    $(basename space) $vlan_id: $(get_vlan_ip $vlan_id 0)/21"
         fi
     done
 
@@ -558,6 +605,39 @@ function space_delete() {
 }
 
 
+#
+# Subnet commands
+#
+
+function subnet_get() {
+    args=$(check_args space,,$1, region,,$2) || return 1
+    eval $args
+
+    if ! has_section "/spaces/$space" ; then
+        echo "Space does not exist"
+        return 1
+    fi
+
+    if ! has_section "/regions/$region" ; then
+        echo "Region does not exist"
+        return 1
+    fi
+
+    vlan_id=$(get_var "/regions/$region/spaces/$space/vlan")
+
+    echo "Subnet: $(get_vlan_ip $vlan_id 0)/21"
+    echo "Firewall: $(get_vlan_ip $vlan_id 1)"
+    echo "Aggregators:"
+
+    for aggregator in $(list_sections "/aggregators") ; do
+        if [ "$(get_var $aggregator/region)" = $region ] ; then
+            ip=$(get_vlan_ip $vlan_id $(get_var $aggregator/yap_id))
+            echo "    $(get_var $aggregator/name): $ip"
+        fi
+    done
+}
+
+
 #
 # Aggregator commands
 #
@@ -939,6 +1019,9 @@ case "$action" in
     space-delete)
         space_delete "$@"
         ;;
+    subnet-get)
+        subnet_get "$@"
+        ;;
     agg-list|aggregator-list)
         aggregator_list "$@"
         ;;