(#8302) Improve documentation of exec providers

The documentation for the shell and posix providers didn't fully explain the
differences between them or the security implications of each. This commit
improves the documentation of both providers.

2 files changed, 17 insertions, 5 deletions

diff --git a/lib/puppet/provider/exec/posix.rb b/lib/puppet/provider/exec/posix.rb
index 92dbd8c98..157d0f28d 100644
--- a/lib/puppet/provider/exec/posix.rb
+++ b/lib/puppet/provider/exec/posix.rb
@@ -4,9 +4,12 @@ Puppet::Type.type(:exec).provide :posix do
   confine :feature => :posix
   defaultfor :feature => :posix
 
-  desc "Execute external binaries directly, on POSIX systems.
-This does not pass through a shell, or perform any interpolation, but
-only directly calls the command with the arguments given."
+  desc <<-EOT
+    Executes external binaries directly, without passing through a shell or
+    performing any interpolation. This is a safer and more predictable way
+    to execute most commands, but prevents the use of globbing and shell
+    built-ins (including control logic like "for" and "if" statements).
+  EOT
 
   def run(command, check = false)
     output = nil
diff --git a/lib/puppet/provider/exec/shell.rb b/lib/puppet/provider/exec/shell.rb
index 98f309e8f..ad2171005 100644
--- a/lib/puppet/provider/exec/shell.rb
+++ b/lib/puppet/provider/exec/shell.rb
@@ -3,8 +3,17 @@ Puppet::Type.type(:exec).provide :shell, :parent => :posix do
 
   confine :feature => :posix
 
-  desc "Execute external binaries directly, on POSIX systems.
-passing through a shell so that shell built ins are available."
+  desc <<-EOT
+    Passes the provided command through `/bin/sh`; only available on
+    POSIX systems. This allows the use of shell globbing and built-ins, and
+    does not require that the path to a command be fully-qualified. Although
+    this can be more convenient than the `posix` provider, it also means that
+    you need to be more careful with escaping; as ever, with great power comes
+    etc. etc.
+
+    This provider closely resembles the behavior of the `exec` type
+    in Puppet 0.25.x.
+  EOT
 
   def run(command, check = false)
     command = %Q{/bin/sh -c "#{command.gsub(/"/,'\"')}"}