chef 14.15.6 → 18.1.0

data/lib/chef/resource/windows_dns_zone.rb

@@ -0,0 +1,79 @@
+#
+# Author:: Jason Field
+#
+# Copyright:: 2018, Calastone Ltd.
+# Copyright:: Copyright (c) Chef Software Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+require_relative "../resource"
+
+class Chef
+  class Resource
+    class WindowsDnsZone < Chef::Resource
+
+      provides :windows_dns_zone
+
+      description "The windows_dns_zone resource creates an Active Directory Integrated DNS Zone on the local server."
+      introduced "15.0"
+
+      property :zone_name, String,
+        description: "An optional property to set the dns zone name if it differs from the resource block's name.",
+        name_property: true
+
+      property :replication_scope, String,
+        description: "The replication scope for the zone, required if server_type set to 'Domain'.",
+        default: "Domain"
+
+      property :server_type, String,
+        description: "The type of DNS server, Domain or Standalone.",
+        default: "Domain", equal_to: %w{Domain Standalone}
+
+      action :create, description: "Creates and updates a DNS Zone." do
+        powershell_package "xDnsServer"
+
+        run_dsc_resource "Present"
+      end
+
+      action :delete, description: "Deletes a DNS Zone." do
+        powershell_package "xDnsServer"
+
+        run_dsc_resource "Absent"
+      end
+
+      action_class do
+        private
+
+        # @api private
+        def run_dsc_resource(ensure_prop)
+          if new_resource.server_type == "Domain"
+            dsc_resource "xDnsServerADZone #{new_resource.zone_name} #{ensure_prop}" do
+              module_name "xDnsServer"
+              resource :xDnsServerADZone
+              property :Ensure, ensure_prop
+              property :Name, new_resource.zone_name
+              property :ReplicationScope, new_resource.replication_scope
+            end
+          elsif new_resource.server_type == "Standalone"
+            dsc_resource "xDnsServerPrimaryZone #{new_resource.zone_name} #{ensure_prop}" do
+              module_name "xDnsServer"
+              resource :xDnsServerPrimaryZone
+              property :Ensure, ensure_prop
+              property :Name, new_resource.zone_name
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/chef/resource/windows_env.rb

@@ -17,33 +17,214 @@
 # limitations under the License.
 #
 
-require "chef/resource"
+require_relative "../resource"
+require_relative "../mixin/windows_env_helper"
+require "chef-utils/dist" unless defined?(ChefUtils::Dist)
 
 class Chef
   class Resource
     class WindowsEnv < Chef::Resource
-      resource_name :windows_env
+
       provides :windows_env
       provides :env # backwards compat with the pre-Chef 14 resource name
 
-      description "Use the env resource to manage environment keys in Microsoft Windows. After an environment key is set, Microsoft Windows must be restarted before the environment key will be available to the Task Scheduler."
+      description "Use the **windows_env** resource to manage environment keys in Microsoft Windows. After an environment key is set, Microsoft Windows must be restarted before the environment key will be available to the Task Scheduler.\n\nThis resource was previously called the **env** resource; its name was updated in #{ChefUtils::Dist::Infra::PRODUCT} 14.0 to reflect the fact that only Windows is supported. Existing cookbooks using `env` will continue to function, but should be updated to use the new name. Note: On UNIX-based systems, the best way to manipulate environment keys is with the `ENV` variable in Ruby; however, this approach does not have the same permanent effect as using the windows_env resource."
+      examples <<~DOC
+      **Set an environment variable**:
+
+      ```ruby
+      windows_env 'ComSpec' do
+        value 'C:\\Windows\\system32\\cmd.exe'
+      end
+      ```
+      DOC
 
       default_action :create
       allowed_actions :create, :delete, :modify
 
       property :key_name, String,
-               description: "An optional property to set the name of the key that is to be created, deleted, or modified if it differs from the resource block's name.",
-               identity: true, name_property: true
+        description: "An optional property to set the name of the key that is to be created, deleted, or modified if it differs from the resource block's name.",
+        name_property: true
 
       property :value, String,
-               description: "The value of the environmental variable to set.",
-               required: true
+        description: "The value of the environmental variable to set.",
+        required: %i{create modify}
 
       property :delim, [ String, nil, false ],
-               description: "The delimiter that is used to separate multiple values for a single key.",
-               desired_state: false
+        description: "The delimiter that is used to separate multiple values for a single key.",
+        desired_state: false
 
       property :user, String, default: "<System>"
+
+      action_class do
+        include Chef::Mixin::WindowsEnvHelper
+
+        def whyrun_supported?
+          false
+        end
+
+        def load_current_resource
+          @current_resource = Chef::Resource::WindowsEnv.new(new_resource.name)
+          current_resource.key_name(new_resource.key_name)
+
+          if key_exists?
+            current_resource.value(env_value(new_resource.key_name))
+          else
+            logger.trace("#{new_resource} key does not exist")
+          end
+
+          current_resource
+        end
+
+        def key_exists?
+          @key_exists ||= !!env_value(new_resource.key_name)
+        end
+
+        def requires_modify_or_create?
+          if new_resource.delim
+            # e.g. check for existing value within PATH
+            new_values.inject(0) do |index, val|
+              next_index = current_values.find_index val
+              return true if next_index.nil? || next_index < index
+
+              next_index
+            end
+            false
+          else
+            new_resource.value != current_resource.value
+          end
+        end
+
+        alias_method :compare_value, :requires_modify_or_create?
+
+        # e.g. delete a PATH element
+        #
+        # ==== Returns
+        # <true>:: If we handled the element case and caller should not delete the key
+        # <false>:: Caller should delete the key, either no :delim was specific or value was empty
+        #           after we removed the element.
+        def delete_element
+          return false unless new_resource.delim # no delim: delete the key
+
+          needs_delete = new_values.any? { |v| current_values.include?(v) }
+          if !needs_delete
+            logger.trace("#{new_resource} element '#{new_resource.value}' does not exist")
+            true # do not delete the key
+          else
+            new_value =
+              current_values.select do |item|
+                not new_values.include?(item)
+              end.join(new_resource.delim)
+
+            if new_value.empty?
+              false # nothing left here, delete the key
+            else
+              old_value = new_resource.value(new_value)
+              create_env
+              logger.trace("#{new_resource} deleted #{old_value} element")
+              new_resource.updated_by_last_action(true)
+              true # we removed the element and updated; do not delete the key
+            end
+          end
+        end
+
+        def create_env
+          obj = env_obj(@new_resource.key_name)
+          unless obj
+            obj = WIN32OLE.connect("winmgmts://").get("Win32_Environment").spawninstance_
+            obj.name = @new_resource.key_name
+            obj.username = new_resource.user
+          end
+          obj.variablevalue = @new_resource.value
+          obj.put_
+          value = @new_resource.value
+          value = expand_path(value) if @new_resource.key_name.casecmp("PATH") == 0
+          ENV[@new_resource.key_name] = value
+          broadcast_env_change
+        end
+
+        def delete_env
+          obj = env_obj(@new_resource.key_name)
+          if obj
+            obj.delete_
+            broadcast_env_change
+          end
+          if ENV[@new_resource.key_name]
+            ENV.delete(@new_resource.key_name)
+          end
+        end
+
+        def modify_env
+          if new_resource.delim
+            new_resource.value((new_values + current_values).uniq.join(new_resource.delim))
+          end
+          create_env
+        end
+
+        # Returns the current values to split by delimiter
+        def current_values
+          @current_values ||= current_resource.value.split(new_resource.delim)
+        end
+
+        # Returns the new values to split by delimiter
+        def new_values
+          @new_values ||= new_resource.value.split(new_resource.delim)
+        end
+
+        def env_value(key_name)
+          obj = env_obj(key_name)
+          obj.variablevalue if obj
+        end
+
+        def env_obj(key_name)
+          return @env_obj if @env_obj
+
+          wmi = WmiLite::Wmi.new
+          # Note that by design this query is case insensitive with regard to key_name
+          environment_variables = wmi.query("select * from Win32_Environment where name = '#{key_name}'")
+          if environment_variables && environment_variables.length > 0
+            environment_variables.each do |env|
+              @env_obj = env.wmi_ole_object
+              return @env_obj if @env_obj.username.split("\\").last.casecmp(new_resource.user) == 0
+            end
+          end
+          @env_obj = nil
+        end
+      end
+
+      action :create, description: "Create an environment variable. If an environment variable already exists (but does not match), update that environment variable to match." do
+        if key_exists?
+          if requires_modify_or_create?
+            modify_env
+            logger.info("#{new_resource} altered")
+            new_resource.updated_by_last_action(true)
+          end
+        else
+          create_env
+          logger.info("#{new_resource} created")
+          new_resource.updated_by_last_action(true)
+        end
+      end
+
+      action :delete, description: "Delete an environment variable." do
+        if ( ENV[new_resource.key_name] || key_exists? ) && !delete_element
+          delete_env
+          logger.info("#{new_resource} deleted")
+          new_resource.updated_by_last_action(true)
+        end
+      end
+
+      action :modify, description: "Modify an existing environment variable. This prepends the new value to the existing value, using the delimiter specified by the `delim` property." do
+        if key_exists?
+          if requires_modify_or_create?
+            modify_env
+            logger.info("#{new_resource} modified")
+            new_resource.updated_by_last_action(true)
+          end
+        else
+          raise Chef::Exceptions::WindowsEnv, "Cannot modify #{new_resource} - key does not exist!"
+        end
+      end
     end
   end
 end

data/lib/chef/resource/windows_feature.rb

@@ -1,7 +1,7 @@
 #
 # Author:: Seth Chisamore (<schisamo@chef.io>)
 #
-# Copyright:: 2011-2018, Chef Software, Inc.
+# Copyright:: Copyright (c) Chef Software Inc.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -16,60 +16,112 @@
 # limitations under the License.
 #
 
-require "chef/resource"
+require_relative "../resource"
 
 class Chef
   class Resource
     class WindowsFeature < Chef::Resource
-      resource_name :windows_feature
+
       provides(:windows_feature) { true }
 
-      description "Use the windows_feature resource to add, remove or entirely delete Windows features and roles. This resource calls the 'windows_feature_dism' or 'windows_feature_powershell' resources depending on the specified installation method and defaults to dism, which is available on both Workstation and Server editions of Windows."
+      description "Use the **windows_feature** resource to add, remove or entirely delete Windows features and roles. This resource calls the 'windows_feature_dism' or 'windows_feature_powershell' resources depending on the specified installation method, and defaults to DISM, which is available on both Workstation and Server editions of Windows."
       introduced "14.0"
+      examples <<~DOC
+      **Install the DHCP Server feature**:
+
+      ```ruby
+      windows_feature 'DHCPServer' do
+        action :install
+      end
+      ```
+
+      **Install the .Net 3.5.1 feature using repository files on DVD**:
+
+      ```ruby
+      windows_feature "NetFx3" do
+        action :install
+        source 'd:\\sources\\sxs'
+      end
+      ```
+
+      **Remove Telnet Server and Client features**:
+
+      ```ruby
+      windows_feature %w(TelnetServer TelnetClient) do
+        action :remove
+      end
+      ```
+
+      **Add the SMTP Server feature using the PowerShell provider**:
+
+      ```ruby
+      windows_feature 'smtp-server' do
+        action :install
+        all true
+        install_method :windows_feature_powershell
+      end
+      ```
+
+      **Install multiple features using one resource with the PowerShell provider**:
+
+      ```ruby
+      windows_feature %w(Web-Asp-Net45 Web-Net-Ext45) do
+        action :install
+        install_method :windows_feature_powershell
+      end
+      ```
+
+      **Install the Network Policy and Access Service feature, including the management tools**:
+
+      ```ruby
+      windows_feature 'NPAS' do
+        action :install
+        management_tools true
+        install_method :windows_feature_powershell
+      end
+      ```
+      DOC
 
       property :feature_name, [Array, String],
-               description: "The name of the feature(s) or role(s) to install if they differ from the resource block's name. The same feature may have different names depending on the underlying installation method being used (ie DHCPServer vs DHCP; DNS-Server-Full-Role vs DNS).",
-               name_property: true
+        description: "The name of the feature(s) or role(s) to install if they differ from the resource block's name. The same feature may have different names depending on the underlying installation method being used (ie DHCPServer vs DHCP; DNS-Server-Full-Role vs DNS).",
+        name_property: true
 
       property :source, String,
-               description: "Specify a local repository for the feature install."
+        description: "Specify a local repository for the feature install."
 
       property :all, [TrueClass, FalseClass],
-               description: "Install all sub features.",
-               default: false
+        description: "Install all sub-features.",
+        default: false
 
       property :management_tools, [TrueClass, FalseClass],
-               description: "Install all applicable management tools for the roles, role services, or features (PowerShell-only).",
-               default: false
+        description: "Install all applicable management tools for the roles, role services, or features (PowerShell-only).",
+        default: false
 
       property :install_method, Symbol,
-               description: "The underlying installation method to use for feature installation. Specify ':windows_feature_dism' for DISM or ':windows_feature_powershell' for PowerShell.",
-               equal_to: [:windows_feature_dism, :windows_feature_powershell, :windows_feature_servermanagercmd],
-               default: :windows_feature_dism
+        description: "The underlying installation method to use for feature installation. Specify `:windows_feature_dism` for DISM or `:windows_feature_powershell` for PowerShell.",
+        equal_to: %i{windows_feature_dism windows_feature_powershell windows_feature_servermanagercmd},
+        default: :windows_feature_dism
 
       property :timeout, Integer,
-               description: "Specifies a timeout (in seconds) for the feature installation.",
-               default: 600
-
-      action :install do
-        description "Install a Windows role/feature"
+        description: "Specifies a timeout (in seconds) for the feature installation.",
+        default: 600,
+        desired_state: false
 
+      action :install, description: "Install a Windows role or feature." do
         run_default_subresource :install
       end
 
-      action :remove do
-        description "Remove a Windows role/feature"
-
+      action :remove, description: "Remove a Windows role or feature." do
         run_default_subresource :remove
       end
 
-      action :delete do
-        description "Remove a Windows role/feature from the image"
-
+      action :delete, description: "Remove a Windows role or feature from the image." do
         run_default_subresource :delete
       end
 
       action_class do
+        private
+
         # call the appropriate windows_feature resource based on the specified subresource
         # @return [void]
         def run_default_subresource(desired_action)

data/lib/chef/resource/windows_feature_dism.rb

@@ -1,7 +1,7 @@
 #
 # Author:: Seth Chisamore (<schisamo@chef.io>)
 #
-# Copyright:: 2011-2018, Chef Software, Inc.
+# Copyright:: Copyright (c) Chef Software Inc.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -16,59 +16,70 @@
 # limitations under the License.
 #
 
-require "chef/resource"
-require "chef/platform/query_helpers"
+require_relative "../resource"
+require_relative "../platform/query_helpers"
 
 class Chef
   class Resource
     class WindowsFeatureDism < Chef::Resource
-      resource_name :windows_feature_dism
+
       provides(:windows_feature_dism) { true }
 
-      description "Use the windows_feature_dism resource to add, remove, or entirely delete Windows features and roles using DISM."
+      description "Use the **windows_feature_dism** resource to add, remove, or entirely delete Windows features and roles using DISM."
       introduced "14.0"
+      examples <<~DOC
+      **Installing the TelnetClient service**:
+
+      ```ruby
+      windows_feature_dism "TelnetClient"
+      ```
+
+      **Installing two features by using an array**:
+
+      ```ruby
+      windows_feature_dism %w(TelnetClient TFTP)
+      ```
+      DOC
 
       property :feature_name, [Array, String],
-               description: "The name of the feature(s) or role(s) to install if they differ from the resource name.",
-               coerce: proc { |x| to_formatted_array(x) },
-               name_property: true
+        description: "The name of the feature(s) or role(s) to install if they differ from the resource name.",
+        coerce: proc { |x| to_formatted_array(x) },
+        name_property: true
 
       property :source, String,
-               description: "Specify a local repository for the feature install."
+        description: "Specify a local repository for the feature install."
 
       property :all, [TrueClass, FalseClass],
-               description: "Install all sub-features. When set to 'true', this is the equivalent of specifying the /All switch to dism.exe",
-               default: false
+        description: "Install all sub-features. When set to `true`, this is the equivalent of specifying the `/All` switch to `dism.exe`",
+        default: false
 
       property :timeout, Integer,
-               description: "Specifies a timeout (in seconds) for the feature installation.",
-               default: 600
+        description: "Specifies a timeout (in seconds) for the feature installation.",
+        default: 600,
+        desired_state: false
 
-      # @return [Array] lowercase the array unless we're on < Windows 2012
+      # @return [Array] lowercase the array
       def to_formatted_array(x)
         x = x.split(/\s*,\s*/) if x.is_a?(String) # split multiple forms of a comma separated list
-
-        # feature installs on windows < 2012 are case sensitive so only downcase when on 2012+
-        older_than_win_2012_or_8? ? x : x.map(&:downcase)
+        x.map(&:downcase)
       end
 
-      action :install do
-        description "Install a Windows role/feature using DISM"
-
+      action :install, description: "Install a Windows role/feature using DISM." do
         reload_cached_dism_data unless node["dism_features_cache"]
         fail_if_unavailable # fail if the features don't exist
 
-        logger.trace("Windows features needing installation: #{features_to_install.empty? ? 'none' : features_to_install.join(',')}")
+        logger.trace("Windows features needing installation: #{features_to_install.empty? ? "none" : features_to_install.join(",")}")
         unless features_to_install.empty?
-          message = "install Windows feature#{'s' if features_to_install.count > 1} #{features_to_install.join(',')}"
+          message = "install Windows feature#{"s" if features_to_install.count > 1} #{features_to_install.join(",")}"
           converge_by(message) do
-            install_command = "dism.exe /online /enable-feature #{features_to_install.map { |f| "/featurename:#{f}" }.join(' ')} /norestart"
+            install_command = "dism.exe /online /enable-feature #{features_to_install.map { |f| "/featurename:#{f}" }.join(" ")} /norestart"
             install_command << " /LimitAccess /Source:\"#{new_resource.source}\"" if new_resource.source
             install_command << " /All" if new_resource.all
             begin
               shell_out!(install_command, returns: [0, 42, 127, 3010], timeout: new_resource.timeout)
             rescue Mixlib::ShellOut::ShellCommandFailed => e
               raise "Error 50 returned by DISM related to parent features, try setting the 'all' property to 'true' on the 'windows_feature_dism' resource." if required_parent_feature?(e.inspect)
+
               raise e.message
             end
 
@@ -77,37 +88,31 @@ class Chef
         end
       end
 
-      action :remove do
-        description "Remove a Windows role/feature using DISM"
-
+      action :remove, description: "Remove a Windows role or feature using DISM." do
         reload_cached_dism_data unless node["dism_features_cache"]
 
-        logger.trace("Windows features needing removal: #{features_to_remove.empty? ? 'none' : features_to_remove.join(',')}")
+        logger.trace("Windows features needing removal: #{features_to_remove.empty? ? "none" : features_to_remove.join(",")}")
         unless features_to_remove.empty?
-          message = "remove Windows feature#{'s' if features_to_remove.count > 1} #{features_to_remove.join(',')}"
+          message = "remove Windows feature#{"s" if features_to_remove.count > 1} #{features_to_remove.join(",")}"
 
           converge_by(message) do
-            shell_out!("dism.exe /online /disable-feature #{features_to_remove.map { |f| "/featurename:#{f}" }.join(' ')} /norestart", returns: [0, 42, 127, 3010], timeout: new_resource.timeout)
+            shell_out!("dism.exe /online /disable-feature #{features_to_remove.map { |f| "/featurename:#{f}" }.join(" ")} /norestart", returns: [0, 42, 127, 3010], timeout: new_resource.timeout)
 
             reload_cached_dism_data # Reload cached dism feature state
           end
         end
       end
 
-      action :delete do
-        description "Remove a Windows role/feature from the image using DISM"
-
-        raise_if_delete_unsupported
-
+      action :delete, description: "Remove a Windows role or feature from the image using DISM." do
         reload_cached_dism_data unless node["dism_features_cache"]
 
         fail_if_unavailable # fail if the features don't exist
 
-        logger.trace("Windows features needing deletion: #{features_to_delete.empty? ? 'none' : features_to_delete.join(',')}")
+        logger.trace("Windows features needing deletion: #{features_to_delete.empty? ? "none" : features_to_delete.join(",")}")
         unless features_to_delete.empty?
-          message = "delete Windows feature#{'s' if features_to_delete.count > 1} #{features_to_delete.join(',')} from the image"
+          message = "delete Windows feature#{"s" if features_to_delete.count > 1} #{features_to_delete.join(",")} from the image"
           converge_by(message) do
-            shell_out!("dism.exe /online /disable-feature #{features_to_delete.map { |f| "/featurename:#{f}" }.join(' ')} /Remove /norestart", returns: [0, 42, 127, 3010], timeout: new_resource.timeout)
+            shell_out!("dism.exe /online /disable-feature #{features_to_delete.map { |f| "/featurename:#{f}" }.join(" ")} /Remove /norestart", returns: [0, 42, 127, 3010], timeout: new_resource.timeout)
 
             reload_cached_dism_data # Reload cached dism feature state
           end
@@ -115,6 +120,8 @@ class Chef
       end
 
       action_class do
+        private
+
         # @return [Array] features the user has requested to install which need installation
         def features_to_install
           @install ||= begin
@@ -158,9 +165,15 @@ class Chef
 
           # the difference of desired features to install to all features is what's not available
           unavailable = (new_resource.feature_name - all_available)
-          raise "The Windows feature#{'s' if unavailable.count > 1} #{unavailable.join(',')} #{unavailable.count > 1 ? 'are' : 'is'} not available on this version of Windows. Run 'dism /online /Get-Features' to see the list of available feature names." unless unavailable.empty?
+          raise "The Windows feature#{"s" if unavailable.count > 1} #{unavailable.join(",")} #{unavailable.count > 1 ? "are" : "is"} not available on this version of Windows. Run 'dism /online /Get-Features' to see the list of available feature names." unless unavailable.empty?
         end
 
+        #
+        # FIXME FIXME FIXME
+        # The node object should not be used for caching state like this and this is not a public API and may break.
+        # FIXME FIXME FIXME
+        #
+
         # run dism.exe to get a list of all available features and their state
         # and save that to the node at node.override level.
         # We do this because getting a list of features in dism takes at least a second
@@ -189,30 +202,21 @@ class Chef
               add_to_feature_mash("disabled", feature_details_raw)
             end
           end
-          logger.trace("The cache contains\n#{node['dism_features_cache']}")
+          logger.trace("The cache contains\n#{node["dism_features_cache"]}")
         end
 
-        # parse the feature string and add the values to the appropriate array
-        # in the
-        # strips trailing whitespace characters then split on n number of spaces
-        # + | +  n number of spaces
+        # parse the feature string and add the values to the appropriate array in the strips
+        # trailing whitespace characters then split on n number of spaces + | +  n number of spaces
         # @return [void]
         def add_to_feature_mash(feature_type, feature_string)
           feature_details = feature_string.strip.split(/\s+[|]\s+/).first
 
-          # dism on windows 2012+ isn't case sensitive so it's best to compare
-          # lowercase lists so the user input doesn't need to be case sensitive
-          # @todo when we're ready to remove windows 2008R2 the gating here can go away
-          feature_details.downcase! unless older_than_win_2012_or_8?
+          # dism isn't case sensitive so it's best to compare lowercase lists so the
+          # user input doesn't need to be case sensitive
+          feature_details.downcase!
           node.override["dism_features_cache"][feature_type] << feature_details
         end
 
-        # Fail unless we're on windows 8+ / 2012+ where deleting a feature is supported
-        # @return [void]
-        def raise_if_delete_unsupported
-          raise Chef::Exceptions::UnsupportedAction, "#{self} :delete action not supported on Windows releases before Windows 8/2012. Cannot continue!" if older_than_win_2012_or_8?
-        end
-
         def required_parent_feature?(error_message)
           error_message.include?("Error: 50") && error_message.include?("required parent feature")
         end