Merge pull request #10530 from chef/test_ifconfig

Signed-off-by: Tim Smith <tsmith@chef.io>

4 files changed, 67 insertions, 7 deletions

diff --git a/kitchen-tests/cookbooks/end_to_end/recipes/_ifconfig.rb b/kitchen-tests/cookbooks/end_to_end/recipes/_ifconfig.rb
new file mode 100644
index 0000000000..149b2cb65c
--- /dev/null
+++ b/kitchen-tests/cookbooks/end_to_end/recipes/_ifconfig.rb
@@ -0,0 +1,13 @@
+execute "create virtual interface for testing" do
+  command "ifconfig eth0:0 123.123.22.22"
+end
+
+ifconfig "33.33.33.80" do
+  bootproto "dhcp"
+  device "eth0:0"
+end
+
+ifconfig "Set eth1 to DHCP" do
+  device "eth0:0"
+  bootproto "dhcp"
+end
\ No newline at end of file
diff --git a/kitchen-tests/cookbooks/end_to_end/recipes/linux.rb b/kitchen-tests/cookbooks/end_to_end/recipes/linux.rb
index 0d560b09bd..8991cf1594 100644
--- a/kitchen-tests/cookbooks/end_to_end/recipes/linux.rb
+++ b/kitchen-tests/cookbooks/end_to_end/recipes/linux.rb
@@ -123,6 +123,7 @@ include_recipe "::_ohai_hint"
 include_recipe "::_openssl"
 include_recipe "::_tests"
 include_recipe "::_mount"
+include_recipe "::_ifconfig"
 
 # at the moment these do not run properly in docker
 # we need to investigate if this is a snap on docker issue or a chef issue
diff --git a/kitchen-tests/kitchen.yml b/kitchen-tests/kitchen.yml
index 0cae421d9f..2f453d9133 100644
--- a/kitchen-tests/kitchen.yml
+++ b/kitchen-tests/kitchen.yml
@@ -54,6 +54,7 @@ platforms:
     pid_one_command: /bin/systemd
     intermediate_instructions:
       - RUN /usr/bin/apt-get update
+      - RUN /usr/bin/apt-get install ifupdown -y # we need this for /etc/network/interfaces & ifconfig resource
 
 - name: debian-10
   driver:
@@ -61,6 +62,7 @@ platforms:
     pid_one_command: /bin/systemd
     intermediate_instructions:
       - RUN /usr/bin/apt-get update
+      - RUN /usr/bin/apt-get install ifupdown -y # we need this for /etc/network/interfaces & ifconfig resource
 
 - name: centos-6
   driver:
@@ -125,6 +127,7 @@ platforms:
     pid_one_command: /bin/systemd
     intermediate_instructions:
       - RUN /usr/bin/apt-get update
+      - RUN /usr/bin/apt-get install ifupdown -y # we need this for /etc/network/interfaces & ifconfig resource
 
 - name: ubuntu-20.04
   driver:
@@ -132,6 +135,7 @@ platforms:
     pid_one_command: /bin/systemd
     intermediate_instructions:
       - RUN /usr/bin/apt-get update
+      - RUN /usr/bin/apt-get install ifupdown -y # we need this for /etc/network/interfaces & ifconfig resource testing
 
 - name: opensuse-leap-15
   driver:
@@ -139,8 +143,7 @@ platforms:
     pid_one_command: /bin/systemd
     intermediate_instructions:
       - RUN /usr/bin/zypper --non-interactive update
-      - RUN /usr/bin/zypper --non-interactive install cron
-      - RUN /usr/bin/zypper --non-interactive install insserv-compat
+      - RUN /usr/bin/zypper --non-interactive install insserv-compat net-tools-deprecated # net-tools-deprecated is necessary for fconfig resource testing
 
 suites:
   - name: end-to-end
diff --git a/lib/chef/resource/ifconfig.rb b/lib/chef/resource/ifconfig.rb
index 091b95a579..223e10967f 100644
--- a/lib/chef/resource/ifconfig.rb
+++ b/lib/chef/resource/ifconfig.rb
@@ -21,16 +21,59 @@ require_relative "../resource"
 
 class Chef
   class Resource
-    # @example set a static ip on eth1
-    #   ifconfig '33.33.33.80' do
-    #     device 'eth1'
-    #   end
     class Ifconfig < Chef::Resource
       unified_mode true
 
       provides :ifconfig
 
-      description "Use the **ifconfig** resource to manage interfaces on Unix and Linux systems."
+      description "Use the **ifconfig** resource to manage interfaces on Unix and Linux systems. Note: This resource requires the ifconfig binary to be present on the system and may require additional packages to be installed first. On Ubuntu 18.04 or later you will need to install the `ifupdown` package, which disables the built in Netplan functionality."
+      examples <<~DOC
+      **Configure a network interface with a static IP**
+
+      ```ruby
+      ifconfig '33.33.33.80' do
+        device 'eth1'
+      end
+      ```
+
+      will create the following interface configuration:
+
+      ```
+      iface eth1 inet static
+        address 33.33.33.80
+      ```
+
+      **Configure an interface to use DHCP**
+
+      ```ruby
+      ifconfig 'Set eth1 to DHCP' do
+        device 'eth1'
+        bootproto 'dhcp'
+      end
+      ```
+
+      will create the following interface configuration:
+
+      ```
+      iface eth1 inet dhcp
+      ```
+
+      **Update a static IP address with a boot protocol**
+
+      ```ruby
+      ifconfig "33.33.33.80" do
+        bootproto "dhcp"
+        device "eth1"
+      end
+      ```
+
+      will update the interface configuration from static to dhcp:
+
+      ```
+      iface eth1 inet dhcp
+        address 33.33.33.80
+      ```
+      DOC
 
       state_attrs :inet_addr, :mask