diff --git a/gns3server/compute/docker/docker_vm.py b/gns3server/compute/docker/docker_vm.py
index 6a04f64d5..666844875 100644
--- a/gns3server/compute/docker/docker_vm.py
+++ b/gns3server/compute/docker/docker_vm.py
@@ -511,6 +511,11 @@ class DockerVM(BaseNode):
                 f.write("""#
 # This is a sample network config, please uncomment lines to configure the network
 #
+# NOTE: at boot /gns3/init.sh applies this file with BusyBox ifup ("ifup -a -f").
+# BusyBox ifupdown only brings up "auto" stanzas and requires separate
+# "address <ip>" and "netmask <mask>" lines: CIDR notation such as
+# "address 10.0.0.1/24" is rejected and the interface stays unconfigured.
+#
 
 # Uncomment this line to load custom interface files
 # source /etc/network/interfaces.d/*
diff --git a/gns3server/compute/docker/resources/init.sh b/gns3server/compute/docker/resources/init.sh
index 05c6ee2e0..a9488f333 100755
--- a/gns3server/compute/docker/resources/init.sh
+++ b/gns3server/compute/docker/resources/init.sh
@@ -87,6 +87,11 @@ sed -n 's/^ *\(eth[0-9]*\):.*/\1/p' < /proc/net/dev | while read dev; do
 done
 
 # configure network interfaces
+# NOTE: unless the image ships its own ifupdown in /sbin this is BusyBox ifup,
+# which only brings up 'auto' stanzas and does NOT understand CIDR notation:
+# 'address <ip>' and 'netmask <mask>' must be separate lines, otherwise the
+# stanza fails with "don't have all variables for <iface>/inet" and the
+# interface comes up unconfigured.
 ifup -a -f
 
 # continue normal docker startup