Add more indirector documentation.

This adds:
 * general text about the indirector
 * the indirected class for each indirection
 * indirection-specific docs for a few indirections that I could manage to puzzle out
clarify what POST means
restore P:I:Indirection.initialize to its original signature
Be specific about our expectation

Previously, the spec test would sometimes fail because the File.unlink
expectation did not specify a path argument. As a result, if the code
under test unlinked an unrelated file, e.g. tempfile used to write file
content, then the would fail.
fix spec failures
(Maint) Use absolute path for puppet in Gemfile

This allows the use of binstubs to execute puppet from another working
directory.
Merge branch '2.7.x' into 3.1.x

* 2.7.x:
  (Maint) Use absolute path for puppet in Gemfile
Merge branch '3.1.x'

* 3.1.x:
  (Maint) Use absolute path for puppet in Gemfile
Merge pull request #1559 from djmitche/indirdocs

Add more indirector documentation.
(#15561) Add External CA acceptance test

This patch adds three acceptance tests:

  1: Externally issued certificate chains work.
  2: Agent refuses to connect to a master with a cert issued by the
     Agent CA.
  3: Email addresses in certificate names work.
  4: Certificate revocation works.

              +-----------------+
              |     Root CA     |
              |  (Self Signed)  |
              +--+------------+-+
                 |            |
           +-----+            +------+
           |                         |
           v                         v
    +-------------+            +------------+
    | Issuing CA  |            | Issuing CA |
    | For Masters |            | For Agents |
    +-------+-----+            +------+-----+
            |                         |
            |                         |
            v                         v
    +-------------+            +-------------+
    | Master SSL  |            | Agent SSL   |
    | Certificate |            | Certificate |
    +-------------+            +-------------+

A master may restrict clients to those with a certificate issued by a
specific DN.  For example, the Apache `SSLRequire %{SSL_CLIENT_I_DN_CN}
== "Agent CA"` directive will only allow agent with certificates issued
by "Agent CA"

These examples exercise Puppet agents checking for revoked master
certificates by populating a CRL file out of band.

Finally, subject names with email addresses in the name are checked in
an effort to prevent regressions on #15561.  For example,
`CN=agent-email3.example.org/emailAddress=test@example.com`.

This fixture data is intended for, and supported on, EL-6 master hosts
with Apache 2.2 or later and Passenger 3.0.17 from EPEL.

This test is confined to the `el-6` platform.

Expected output on the agent when the master certificate has been
revoked is:

    Error: Could not retrieve catalog from remote server:
    SSL_connect returned=1 errno=0 state=SSLv3 read server certificate B: certificate verify failed:
    [certificate revoked for /CN=master1.example.org]
    Error: Could not retrieve catalog; skipping run
WIP Remove the test where an agent connect to another agent

We cannot support this behavior of refusing to connect to another server
with a SSL certificate issued by another intermediate CA off the common
root.

The `ssl_client_ca_chain` setting is not implemented, so the
`ssl_client_ca_auth` option must be used.

It's unclear if this option can ever work, digging into the guts of the
way the SSLStore class works.  It is also unclear if the
`ssl_client_ca_auth` option is actually doing what I think it's doing.
We assign the localcacert in `puppet/ssl/host`, and I suspect this has
the effect of overriding the use of `ssl_client_ca_auth` in 30eb983