Maint: Correct docs for filebucket type and file's backup parameter

There's a known bug that prevents remote filebucket resources from working
unless you set path => false. Until this bug is fixed, the docs should reflect
reality as she is played. This commit mentions the bug in both areas where it
is relevant.

2 files changed, 24 insertions, 14 deletions

diff --git a/lib/puppet/type/file.rb b/lib/puppet/type/file.rb
index 5215be621..9cac37f27 100644
--- a/lib/puppet/type/file.rb
+++ b/lib/puppet/type/file.rb
@@ -75,16 +75,18 @@ Puppet::Type.newtype(:file) do
 
       Puppet automatically creates a local filebucket named `puppet` and
       defaults to backing up there.  To use a server-based filebucket,
-      you must specify one in your configuration
+      you must specify one in your configuration.
 
             filebucket { main:
-              server => puppet
+              server => puppet,
+              path   => false,
+              # The path => false line works around a known issue with the filebucket type.
             }
 
       The `puppet master` daemon creates a filebucket by default,
       so you can usually back up to your main server with this
       configuration.  Once you've described the bucket in your
-      configuration, you can use it in any file
+      configuration, you can use it in any file's backup attribute:
 
             file { \"/my/file\":
               source => \"/path/in/nfs/or/something\",
@@ -93,12 +95,12 @@ Puppet::Type.newtype(:file) do
 
       This will back the file up to the central server.
 
-      At this point, the benefits of using a filebucket are that you do not
-      have backup files lying around on each of your machines, a given
-      version of a file is only backed up once, and you can restore
-      any given file manually, no matter how old.  Eventually,
-      transactional support will be able to automatically restore
-      filebucketed files.
+      At this point, the benefits of using a central filebucket are that you
+      do not have backup files lying around on each of your machines, a given
+      version of a file is only backed up once, you can restore any given file
+      manually (no matter how old), and you can use Puppet Dashboard to view
+      file contents.  Eventually, transactional support will be able to
+      automatically restore filebucketed files.
       "
 
     defaultto "puppet"
diff --git a/lib/puppet/type/filebucket.rb b/lib/puppet/type/filebucket.rb
index 7fd2ef46b..59174161b 100755
--- a/lib/puppet/type/filebucket.rb
+++ b/lib/puppet/type/filebucket.rb
@@ -11,15 +11,20 @@ module Puppet
       it can be specified as the value of *backup* in a **file** object.
 
       Currently, filebuckets are only useful for manual retrieval of
-      accidentally removed files (e.g., you look in the log for the md5 sum and retrieve the file with that sum from the filebucket), but
-      when transactions are fully supported filebuckets will be used to
-      undo transactions.
+      accidentally removed files (e.g., you look in the log for the md5 sum
+      and retrieve the file with that sum from the filebucket), but when
+      transactions are fully supported filebuckets will be used to undo
+      transactions.
 
       You will normally want to define a single filebucket for your
       whole network and then use that as the default backup location:
 
           # Define the bucket
-          filebucket { main: server => puppet }
+          filebucket { 'main':
+            server => puppet,
+            path   => false,
+            # Due to a known issue, path must be set to false for remote filebuckets.
+          }
 
           # Specify it as the default target
           File { backup => main }
@@ -36,7 +41,10 @@ module Puppet
       desc "The server providing the remote filebucket.  If this is not
         specified then *path* is checked. If it is set, then the
         bucket is local.  Otherwise the puppetmaster server specified
-        in the config or at the commandline is used."
+        in the config or at the commandline is used.
+        
+        Due to a known issue, you currently must set the `path` attribute to
+        false if you wish to specify a `server` attribute."
       defaultto { Puppet[:server] }
     end