Update network config docs to clarify MAC address quoting (#623)

Also update MAC addresses used in testcases to remove quotes where not
required and add single quotes where quotes are required.

3 files changed, 57 insertions, 32 deletions

diff --git a/doc/rtd/topics/network-config-format-v1.rst b/doc/rtd/topics/network-config-format-v1.rst
index dfbde514..92e81897 100644
--- a/doc/rtd/topics/network-config-format-v1.rst
+++ b/doc/rtd/topics/network-config-format-v1.rst
@@ -64,6 +64,14 @@ structure.
 The MAC Address is a device unique identifier that most Ethernet-based network
 devices possess.  Specifying a MAC Address is optional.
 
+.. note::
+
+  MAC addresses must be strings. As MAC addresses which consist of only the
+  digits 0-9 (i.e. no hex a-f) can be interpreted as a base 60 integer per
+  the `YAML 1.1 spec`_ it is best practice to quote all MAC addresses to ensure
+  they are parsed as strings regardless of value.
+
+.. _YAML 1.1 spec: https://yaml.org/type/int.html
 
 .. note::
 
@@ -91,7 +99,7 @@ packet- or frame-based network.  Specifying ``mtu`` is optional.
       # Simple network adapter
       - type: physical
         name: interface0
-        mac_address: 00:11:22:33:44:55
+        mac_address: '00:11:22:33:44:55'
       # Second nic with Jumbo frames
       - type: physical
         name: jumbo0
@@ -124,6 +132,14 @@ bond interfaces.  Specifying a MAC Address is optional.  If ``mac_address`` is
 not present, then the bond will use one of the MAC Address values from one of
 the bond interfaces.
 
+.. note::
+
+  MAC addresses must be strings. As MAC addresses which consist of only the
+  digits 0-9 (i.e. no hex a-f) can be interpreted as a base 60 integer per
+  the `YAML 1.1 spec`_ it is best practice to quote all MAC addresses to ensure
+  they are parsed as strings regardless of value.
+
+.. _YAML 1.1 spec: https://yaml.org/type/int.html
 
 **bond_interfaces**: *<List of network device names>*
 
@@ -194,7 +210,7 @@ Valid ``params`` keys are:
       # Simple network adapter
       - type: physical
         name: interface0
-        mac_address: 00:11:22:33:44:55
+        mac_address: '00:11:22:33:44:55'
       # 10G pair
       - type: physical
         name: gbe0
@@ -246,7 +262,7 @@ Valid keys are:
       # Simple network adapter
       - type: physical
         name: interface0
-        mac_address: 00:11:22:33:44:55
+        mac_address: '00:11:22:33:44:55'
       # Second nic with Jumbo frames
       - type: physical
         name: jumbo0
@@ -303,7 +319,7 @@ packet- or frame-based network.  Specifying ``mtu`` is optional.
        # Physical interfaces.
        - type: physical
          name: eth0
-         mac_address: "c0:d6:9f:2c:e8:80"
+         mac_address: c0:d6:9f:2c:e8:80
        # VLAN interface.
        - type: vlan
          name: eth0.101
@@ -327,7 +343,7 @@ the following keys:
     config:
       - type: physical
         name: interface0
-        mac_address: 00:11:22:33:44:55
+        mac_address: '00:11:22:33:44:55'
         subnets:
            - type: static
              address: 192.168.23.14/27
@@ -358,7 +374,7 @@ has the following keys:
     config:
       - type: physical
         name: interface0
-        mac_address: 00:11:22:33:44:55
+        mac_address: '00:11:22:33:44:55'
         subnets:
            - type: static
              address: 192.168.23.14/24
@@ -410,7 +426,7 @@ the subnet dictionary.
      config:
        - type: physical
          name: interface0
-         mac_address: 00:11:22:33:44:55
+         mac_address: '00:11:22:33:44:55'
          subnets:
            - type: dhcp
 
@@ -422,7 +438,7 @@ the subnet dictionary.
      config:
        - type: physical
          name: interface0
-         mac_address: 00:11:22:33:44:55
+         mac_address: '00:11:22:33:44:55'
          subnets:
            - type: static
              address: 192.168.23.14/27
@@ -443,7 +459,7 @@ using the static subnet configuration.
      config:
        - type: physical
          name: interface0
-         mac_address: 00:11:22:33:44:55
+         mac_address: '00:11:22:33:44:55'
          subnets:
            - type: dhcp
            - type: static
@@ -462,7 +478,7 @@ using the static subnet configuration.
      config:
        - type: physical
          name: interface0
-         mac_address: 00:11:22:33:44:55
+         mac_address: '00:11:22:33:44:55'
          subnets:
            - type: dhcp
            - type: static
diff --git a/doc/rtd/topics/network-config-format-v2.rst b/doc/rtd/topics/network-config-format-v2.rst
index c93e29be..aa17bef5 100644
--- a/doc/rtd/topics/network-config-format-v2.rst
+++ b/doc/rtd/topics/network-config-format-v2.rst
@@ -94,7 +94,16 @@ NetworkManager does not.
 
 **macaddress**: *<(scalar)>*
 
-Device's MAC address in the form "XX:XX:XX:XX:XX:XX". Globs are not allowed.
+Device's MAC address in the form XX:XX:XX:XX:XX:XX. Globs are not allowed.
+
+.. note::
+
+  MAC addresses must be strings. As MAC addresses which consist of only the
+  digits 0-9 (i.e. no hex a-f) can be interpreted as a base 60 integer per
+  the `YAML 1.1 spec`_ it is best practice to quote all MAC addresses to ensure
+  they are parsed as strings regardless of value.
+
+.. _YAML 1.1 spec: https://yaml.org/type/int.html
 
 **driver**: *<(scalar)>*
 
@@ -458,7 +467,7 @@ This is a complex example which shows most available features: ::
       # opaque ID for physical interfaces, only referred to by other stanzas
       id0:
         match:
-          macaddress: 00:11:22:33:44:55
+          macaddress: '00:11:22:33:44:55'
         wakeonlan: true
         dhcp4: true
         addresses:
diff --git a/tests/unittests/test_net.py b/tests/unittests/test_net.py
index 207e47bb..642e60cc 100644
--- a/tests/unittests/test_net.py
+++ b/tests/unittests/test_net.py
@@ -910,7 +910,7 @@ NETWORK_CONFIGS = {
                 # Physical interfaces.
                 - type: physical
                   name: eth99
-                  mac_address: "c0:d6:9f:2c:e8:80"
+                  mac_address: c0:d6:9f:2c:e8:80
                   subnets:
                       - type: dhcp4
                       - type: static
@@ -926,7 +926,7 @@ NETWORK_CONFIGS = {
                             metric: 10000
                 - type: physical
                   name: eth1
-                  mac_address: "cf:d6:af:48:e8:80"
+                  mac_address: cf:d6:af:48:e8:80
                 - type: nameserver
                   address:
                     - 1.2.3.4
@@ -1743,26 +1743,26 @@ pre-down route del -net 10.0.0.0/8 gw 11.0.0.1 metric 3 || true
                 # Physical interfaces.
                 - type: physical
                   name: eth0
-                  mac_address: "c0:d6:9f:2c:e8:80"
+                  mac_address: c0:d6:9f:2c:e8:80
                 - type: physical
                   name: eth1
-                  mac_address: "aa:d6:9f:2c:e8:80"
+                  mac_address: aa:d6:9f:2c:e8:80
                 - type: physical
                   name: eth2
-                  mac_address: "c0:bb:9f:2c:e8:80"
+                  mac_address: c0:bb:9f:2c:e8:80
                 - type: physical
                   name: eth3
-                  mac_address: "66:bb:9f:2c:e8:80"
+                  mac_address: 66:bb:9f:2c:e8:80
                 - type: physical
                   name: eth4
-                  mac_address: "98:bb:9f:2c:e8:80"
+                  mac_address: 98:bb:9f:2c:e8:80
                 # specify how ifupdown should treat iface
                 # control is one of ['auto', 'hotplug', 'manual']
                 # with manual meaning ifup/ifdown should not affect the iface
                 # useful for things like iscsi root + dhcp
                 - type: physical
                   name: eth5
-                  mac_address: "98:bb:9f:2c:e8:8a"
+                  mac_address: 98:bb:9f:2c:e8:8a
                   subnets:
                     - type: dhcp
                       control: manual
@@ -1793,7 +1793,7 @@ pre-down route del -net 10.0.0.0/8 gw 11.0.0.1 metric 3 || true
                   name: bond0
                   # if 'mac_address' is omitted, the MAC is taken from
                   # the first slave.
-                  mac_address: "aa:bb:cc:dd:ee:ff"
+                  mac_address: aa:bb:cc:dd:ee:ff
                   bond_interfaces:
                     - eth1
                     - eth2
@@ -1888,13 +1888,13 @@ pre-down route del -net 10.0.0.0/8 gw 11.0.0.1 metric 3 || true
             config:
               - type: physical
                 name: bond0s0
-                mac_address: "aa:bb:cc:dd:e8:00"
+                mac_address: aa:bb:cc:dd:e8:00
               - type: physical
                 name: bond0s1
-                mac_address: "aa:bb:cc:dd:e8:01"
+                mac_address: aa:bb:cc:dd:e8:01
               - type: bond
                 name: bond0
-                mac_address: "aa:bb:cc:dd:e8:ff"
+                mac_address: aa:bb:cc:dd:e8:ff
                 mtu: 9000
                 bond_interfaces:
                   - bond0s0
@@ -2042,12 +2042,12 @@ iface bond0 inet6 static
               eth0:
                 match:
                     driver: "virtio_net"
-                    macaddress: "aa:bb:cc:dd:e8:00"
+                    macaddress: aa:bb:cc:dd:e8:00
               vf0:
                 set-name: vf0
                 match:
                     driver: "e1000"
-                    macaddress: "aa:bb:cc:dd:e8:01"
+                    macaddress: aa:bb:cc:dd:e8:01
             bonds:
               bond0:
                 addresses:
@@ -2221,7 +2221,7 @@ iface bond0 inet6 static
             config:
               - type: physical
                 name: en0
-                mac_address: "aa:bb:cc:dd:e8:00"
+                mac_address: aa:bb:cc:dd:e8:00
               - type: vlan
                 mtu: 2222
                 name: en0.99
@@ -2294,13 +2294,13 @@ iface bond0 inet6 static
             config:
               - type: physical
                 name: eth0
-                mac_address: "52:54:00:12:34:00"
+                mac_address: '52:54:00:12:34:00'
                 subnets:
                   - type: static
                     address: 2001:1::100/96
               - type: physical
                 name: eth1
-                mac_address: "52:54:00:12:34:01"
+                mac_address: '52:54:00:12:34:01'
                 subnets:
                   - type: static
                     address: 2001:1::101/96
@@ -2385,7 +2385,7 @@ iface bond0 inet6 static
             config:
               - type: physical
                 name: eth0
-                mac_address: "52:54:00:12:34:00"
+                mac_address: '52:54:00:12:34:00'
                 subnets:
                   - type: static
                     address: 192.168.1.2/24
@@ -2393,12 +2393,12 @@ iface bond0 inet6 static
               - type: physical
                 name: eth1
                 mtu: 1480
-                mac_address: "52:54:00:12:34:aa"
+                mac_address: 52:54:00:12:34:aa
                 subnets:
                   - type: manual
               - type: physical
                 name: eth2
-                mac_address: "52:54:00:12:34:ff"
+                mac_address: 52:54:00:12:34:ff
                 subnets:
                   - type: manual
                     control: manual