Add content from PR 5036

Signed-off-by: IanMadd <imaddaus@chef.io>

www/chef-web-docs

@@ -1 +1 @@
-Subproject commit 5b9859aba4ef48f05eb0362972c221a861bbd1f0
+Subproject commit 73077ce55abb6c53629e271c99f3a3161d4941a6

www/content/inspec/resources/interface.md

@@ -12,10 +12,11 @@ platform = "os"
 
 [\[edit on GitHub\]](https://github.com/inspec/inspec/blob/master/www/content/inspec/resources/interface.md)
 
-Use the `interface` Chef InSpec audit resource to test basic network adapter properties, such as name, status, and link speed (in MB/sec).
+Use the `interface` Chef InSpec audit resource to test basic network adapter properties, such as name, status, IP addresses, and link speed (in MB/sec).
 
 - On Linux platforms, `/sys/class/net/#{iface}` is used as source
 - On the Windows platform, the `Get-NetAdapter` cmdlet is used as source
+- On BSD and MacOS platforms, the `ifconfig` command is used as source. Link speed may not be available.
 
 ## Availability
 
@@ -25,7 +26,7 @@ This resource is distributed along with Chef InSpec itself. You can use it autom
 
 ### Version
 
-This resource first became available in v1.0.0 of InSpec.
+This resource first became available in v1.0.0 of Chef InSpec.
 
 ## Syntax
 
@@ -35,56 +36,69 @@ An `interface` resource block declares network interface properties to be tested
       it { should be_up }
       its('speed') { should eq 1000 }
       its('name') { should eq eth0 }
+      its('ipv4_addresses') { should include '10.0.0.5' }
     end
 
 ## Properties
 
-`name`, `speed`
+`ipv4_address`, `ipv4_addresses`, `ipv4_addresses_netmask`, `ipv4_cidrs`, `ipv6_addresses`, `ipv6_cidrs`, `name`, `speed`
 
 ## Resource Property Examples
 
-### name
+### ipv4_address
 
-The `name` property tests if the named network interface exists:
+Returns the first `ipv4_addresses` entry as a String. Note: this property is incompatible with ServerSpec, which returns the value including the CIDR range, such as '10.0.0.5/32'.
 
-    its('name') { should eq eth0 }
-
-### speed
-
-The `speed` property tests the speed of the network interface, in MB/sec:
-
-    its('speed') { should eq 1000 }
+    its('ipv4_address') { should eq '10.0.0.5' }
 
 ### ipv4_addresses
 
-The `ipv4_addresses` property tests if the specified address exists on the named network interface:
+The `ipv4_addresses` property returns an Array of IPv4 addresses as Strings. You may then test if the specified address exists on the named network interface:
 
     its('ipv4_addresses') { should include '127.0.0.1' }
 
 ### ipv4_addresses_netmask
 
-The `ipv4_addresses_netmask` property tests if the specified address and netmask exists on the named network interface:
+The `ipv4_addresses_netmask` property returns an Array of Strings with each containing the IPv4 address, a slash, and the netmask. You may then test if the specified address and netmask exists on the named network interface:
 
     its('ipv4_addresses_netmask') { should include '127.0.0.1/255.0.0.0' }
 
+### ipv6_address
+
+Returns the first `ipv6_address` entry. Note: this property is incompatible with ServerSpec, which returns the value including the CIDR range.
+
+    its('ipv6_address') { should eq '2089:98b::faeb' }
+
 ### ipv6_addresses
 
-The `ipv6_addresses` property tests if the specified address exists on the named network interface:
+The `ipv6_addresses` property returns an Array of Strings and tests if the specified address exists on the named network interface:
 
     its('ipv6_addresses') { should include '::1' }
 
 ### ipv4_cidrs
 
-The `ipv4_cidrs` property tests if the specified address and netmask combination exists on the named network interface:
+The `ipv4_cidrs` property returns an Array of Strings and tests if the specified address and netmask combination exists on the named network interface:
 
     its('ipv4_cidrs') { should include '127.0.0.1/8' }
 
 ### ipv6_cidrs
 
-The `ipv6_cidrs` property tests if the specified address and netmask combination exists on the named network interface:
+The `ipv6_cidrs` property returns an Array of Strings and tests if the specified address and netmask combination exists on the named network interface:
 
     its('ipv6_cidrs') { should include '::1/128' }
 
+### name
+
+The `name` property returns the name of the interface:
+
+    its('name') { should eq 'eth0' }
+
+### speed
+
+The `speed` property tests the speed of the network interface, in MB/sec. Note: On BSD and MacOS platforms, this value may be nil, because it difficult to obtain reliably.
+
+    its('speed') { should eq 1000 }
+
 ## Matchers
 
 For a full list of available matchers, please visit our [matchers page](/inspec/matchers/).
@@ -95,7 +109,13 @@ The `be_up` matcher tests if the network interface is available:
 
     it { should be_up }
 
-### have_an_ipv4_address
+### exist
+
+The `exist` matcher tests if the network interface exists:
+
+    it { should exist }
+
+### have\_an\_ipv4\_address
 
 The `have_an_ipv4_address` matcher tests if the network interface has any IPv4 addresses assigned:
 

www/content/inspec/resources/interfaces.md

@@ -0,0 +1,78 @@
++++
+title = "interfaces resource"
+draft = false
+platform = "os"
+
+[menu]
+  [menu.inspec]
+    title = "interfaces"
+    identifier = "inspec/resources/os/interfaces.md interfaces resource"
+    parent = "inspec/resources/os"
++++
+
+[\[edit on GitHub\]](https://github.com/inspec/inspec/blob/master/www/content/inspec/resources/interfaces.md)
+
+Use the `interfaces` Chef InSpec audit resource to test the properties of multiple network interfaces on the system.
+
+## Syntax
+
+An `interfaces` resource block may take no arguments, in which case it will list all interfaces:
+
+    describe interfaces do
+      its('names') { should include 'eth0' }
+    end
+
+An `interfaces` resource block may take a where clause, filtering on a Filter Criterion:
+
+    # All eth- interfaces
+    describe interfaces.where(name: /^eth\d+/)
+      its('names') { should include 'eth0' }
+    end
+
+Like any Chef InSpec resource, you may also use it for data lookup instead of testing:
+
+    # We are an IPv6 shop
+    interfaces.where(name: /^eth/).names do |name|
+      describe interface(name) do
+        it { should have_ipv6_address }
+      end
+    end
+
+    # Obtain the machine's main IP address
+    my_ip = interfaces.ipv4_address
+
+## Filter Criteria
+
+### name
+
+String. The name of an interface.
+
+## Properties
+
+### count
+
+The `count` property returns an Integer describing how many interfaces matched.
+
+  its("count") { should eq 6 }
+
+### ipv4_address
+
+Attempts to guess the "first" "real" IPv4 address on any interface. Looks for interfaces that are up and have IPv4 addresses assigned, then tries to filter out loopback, management (10/8) and local (192.168/16) IP addresses, returning the best of of those that it can; you may still get nil, or a loopback address.  Note that if the machine is behind NAT this will not be the external IP address; use the `http` resource to query an IP lookup service for that.
+
+  its('ipv4_address') { should_not eq '127.0.0.1' }
+
+### names
+
+The `names` property returns an Array of Strings representing the names of the interfaces.
+
+  its("names") { should include "eth0" }
+
+## Matchers
+
+For a full list of available universal matchers, please visit our [matchers page](https://www.inspec.io/docs/reference/matchers/).
+
+### exist
+
+The `exist` matcher tests true if at least one interface exists on the system. This is almost always the case.
+
+    it { should exist }