From f50f635afe5da4e8971ec36719bdc9249cda2d0e Mon Sep 17 00:00:00 2001
From: dermotbradley <dermot_bradley@yahoo.com>
Date: Tue, 27 Oct 2020 20:54:30 +0000
Subject: 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.
---
doc/rtd/topics/network-config-format-v1.rst | 36 ++++++++++++++++++--------
doc/rtd/topics/network-config-format-v2.rst | 13 ++++++++--
tests/unittests/test_net.py | 40 ++++++++++++++---------------
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
--
cgit v1.2.3