apache resource: document and deprecate (#2494)

* Docs for apache resource

Signed-off-by: kgarmoe <kgarmoe@chef.io>

* Add deprecation warning to apache docs and resource, and clean up examples.

Signed-off-by: Adam Leff <adam@leff.co>

* Update apache_conf resource to remove dependency on apache resource

Signed-off-by: Adam Leff <adam@leff.co>

* Make conf_dir method public

Signed-off-by: Adam Leff <adam@leff.co>

* Removes unnecessary aide_conf commit, pulled in from e25f0a45

Signed-off-by: Adam Leff <adam@leff.co>

* Switch to Pathname to calculate conf_dir

Needed to avoid Windows adding `C:\` in unit tests when calling
File.expand_path.

Signed-off-by: Adam Leff <adam@leff.co>

docs/resources/apache.md.erb

@@ -0,0 +1,66 @@
+---
+title: About the apache Resource
+---
+
+# apache
+
+Use the `apache` InSpec audit resource to test the state of the Apache server on Linux/Unix systems.
+
+<p class="warning">This resource is deprecated and should not be used. It will be removed in InSpec 3.0.</p>
+
+<br>
+
+## Syntax
+
+An `apache` InSpec audit resource block declares settings that should be tested:
+
+    describe apache do
+      its('setting_name') { should cmp 'value' }
+    end
+
+where
+
+* `'setting_name'` is description of the Apache configuration file
+* `{ should cmp 'value' }` is the value that is expected
+
+<br>
+
+## Supported Properties
+
+* 'service', 'conf_dir', 'conf_path', 'user'
+
+<br>
+
+## Property Examples
+
+The following examples show how to use this InSpec audit resource.
+
+### Test the service name.
+
+    describe apache do
+      its ('service') { should cmp 'apache2' }
+    end
+
+### Test the configuration location
+
+    describe apache do
+      its ('conf_dir') { should cmp '/etc/apache2' }
+    end
+
+### Test the path of the configuration file
+
+    describe apache do
+      its ('conf_path') { should cmp '/etc/apache2/apache2.conf' }
+    end
+
+### Test the apache user
+
+    describe apache do
+      its ('user') { should cmp 'www-data' }
+    end
+
+<br>
+
+## Matchers
+
+For a full list of available matchers please visit our [matchers page](https://www.inspec.io/docs/reference/matchers/).

lib/resources/apache.rb

@@ -6,9 +6,29 @@
 module Inspec::Resources
   class Apache < Inspec.resource(1)
     name 'apache'
+    desc 'Use the apache InSpec audit resource to retrieve Apache environment settings.'
+    example "
+      describe apache do
+        its ('service') { should cmp 'apache2' }
+      end
+
+      describe apache do
+        its ('conf_dir') { should cmp '/etc/apache2' }
+      end
+
+      describe apache do
+        its ('conf_path') { should cmp '/etc/apache2/apache2.conf' }
+      end
+
+      describe apache do
+        its ('user') { should cmp 'www-data' }
+      end
+    "
 
     attr_reader :service, :conf_dir, :conf_path, :user
     def initialize
+      warn '[DEPRECATED] The `apache` resource is deprecated and will be removed in InSpec 3.0.'
+
       if inspec.os.debian?
         @service = 'apache2'
         @conf_dir = '/etc/apache2/'

lib/resources/apache_conf.rb

@@ -9,6 +9,8 @@ require 'utils/find_files'
 module Inspec::Resources
   class ApacheConf < Inspec.resource(1)
     name 'apache_conf'
+    supports os_family: 'linux'
+    supports os_family: 'debian'
     desc 'Use the apache_conf InSpec audit resource to test the configuration settings for Apache. This file is typically located under /etc/apache2 on the Debian and Ubuntu platforms and under /etc/httpd on the Fedora, CentOS, Red Hat Enterprise Linux, and Arch Linux platforms. The configuration settings may vary significantly from platform to platform.'
     example "
       describe apache_conf do
@@ -18,9 +20,10 @@ module Inspec::Resources
 
     include FindFiles
 
+    attr_reader :conf_path
+
     def initialize(conf_path = nil)
-      @conf_path = conf_path || inspec.apache.conf_path
-      @conf_dir = conf_path ? File.dirname(@conf_path) : inspec.apache.conf_dir
+      @conf_path = conf_path || default_conf_path
       @files_contents = {}
       @content = nil
       @params = nil
@@ -63,17 +66,17 @@ module Inspec::Resources
       @params = {}
 
       # skip if the main configuration file doesn't exist
-      file = inspec.file(@conf_path)
+      file = inspec.file(conf_path)
       if !file.file?
-        return skip_resource "Can't find file \"#{@conf_path}\""
+        return skip_resource "Can't find file \"#{conf_path}\""
       end
 
       raw_conf = file.content
       if raw_conf.empty? && !file.empty?
-        return skip_resource("Can't read file \"#{@conf_path}\"")
+        return skip_resource("Can't read file \"#{conf_path}\"")
       end
 
-      to_read = [@conf_path]
+      to_read = [conf_path]
       until to_read.empty?
         raw_conf = read_file(to_read[0])
         @content += raw_conf
@@ -111,7 +114,7 @@ module Inspec::Resources
 
       includes = []
       (include_files + include_files_optional).each do |f|
-        id    = Pathname.new(f).absolute? ? f : File.join(@conf_dir, f)
+        id    = Pathname.new(f).absolute? ? f : File.join(conf_dir, f)
         files = find_files(id, depth: 1, type: 'file')
         files += find_files(id, depth: 1, type: 'link')
 
@@ -126,8 +129,30 @@ module Inspec::Resources
       @files_contents[path] ||= inspec.file(path).content
     end
 
+    def conf_dir
+      if inspec.os.debian?
+        File.dirname(conf_path)
+      else
+        # On RHEL-based systems, the configuration is usually in a /conf directory
+        # that contains the primary config file. We assume the "config path" is the
+        # directory that contains the /conf directory, such as /etc/httpd, so that
+        # the conf.d directory can be properly located.
+        Pathname.new(File.dirname(conf_path)).parent.to_s
+      end
+    end
+
     def to_s
-      "Apache Config #{@conf_path}"
+      "Apache Config #{conf_path}"
+    end
+
+    private
+
+    def default_conf_path
+      if inspec.os.debian?
+        '/etc/apache2/apache2.conf'
+      else
+        '/etc/httpd/conf/httpd.conf'
+      end
     end
   end
 end