puppet Documentation

File: README.md Copy Chapter

Puppet

Puppet, an automated administrative engine for your Linux, Unix, and Windows systems, performs
administrative tasks (such as adding users, installing packages, and updating server
configurations) based on a centralized specification.

Documentation Copy Chapter

Documentation for Puppet and related projects can be found online at the
Puppet Docs site.

HTTP API Copy Section

HTTP API Index

Installation Copy Chapter

The best way to run Puppet is with Puppet Enterprise (PE),
which also includes orchestration features, a web console, and professional support.
The PE documentation is available here.

To install an open source release of Puppet,
see the installation guide on the docs site.

If you need to run Puppet from source as a tester or developer,
see the Quick Start to Developing on Puppet guide.

Developing and Contributing Copy Chapter

We'd love to get contributions from you! For a quick guide to getting your
system setup for developing, take a look at our Quickstart
Guide. Once you are up and running, take a look at the
Contribution Documents to see how to get your changes merged
in.

For more complete docs on developing with Puppet, take a look at the
rest of the developer documents.

Licensing Copy Chapter

See LICENSE file. Puppet is licensed by Puppet, Inc. under the Apache license. Puppet, Inc. can be contacted at: [email protected]

Support Copy Chapter

Please log issues in this project's GitHub Issues. A mailing
list is
available for asking questions and getting help from others, or if you prefer chat, we also have a Puppet Community slack.

We use semantic version numbers for our releases and recommend that users stay
as up-to-date as possible by upgrading to patch releases and minor releases as
they become available.

Bug fixes and ongoing development will occur in minor releases for the current
major version. Security fixes will be backported to a previous major version on
a best-effort basis, until the previous major version is no longer maintained.

For example: If a security vulnerability is discovered in Puppet 8.1.1, we
would fix it in the 8 series, most likely as 8.1.2. Maintainers would then make
a best effort to backport that fix onto the latest Puppet 7 release.

Long-term support, including security patches and bug fixes, is available for
commercial customers. Please see the following page for more details:

Puppet Enterprise Support Lifecycle

File: acceptance/README.md Copy Chapter

Running Puppet Acceptance Tests

Table of Contents Copy Chapter

• Setup
• Quick Start
• Configuration
• Running Tests
• Writing Tests
• Getting Help

An important aside: Currently running acceptance tests that contain a specific
change is challenging unless you have access to infrastructure internal to the
Puppet, Inc. network. This is a known issue, and we are working to make this a
better experience for our community.

Setup Copy Chapter

Prerequisites Copy Section

• git
• ruby
• bundler
• a local clone of the puppet repo

All command examples in this readme assume you are working in the same directory
this README is in, puppet/acceptance.

Installation Copy Section

All of the dependencies you need to run and develop tests are defined in
Gemfile. To install them, run bundle install --path .bundle/gems. This
command, as well all the command examples in this README, assume you are working
in the acceptance directory. If you ever have issues with your runtime
dependencies, you can update them with bundle update or start over fresh with
rm -rf .bundle/gems; bundle install --path .bundle/gems.

To ensure installation was successful, you can run bundle exec rake -T. This
should return something along these lines:

$ bundle exec rake -T
rake ci:help               # Print usage information
rake ci:test:aio           # Run the acceptance tests using puppet-agent (AI...
rake ci:test:gem           # Run the acceptance tests against puppet gem on ...
rake ci:test:git           # Run the acceptance tests against a git checkout
rake ci:test:quick         # Run a limited but representative subset of acce...
rake clean                 # Remove any temporary products
rake clobber               # Remove any generated files

To get a detailed description of all of these tasks, run bundle exec rake -D.

Quick Start Copy Chapter

For community members Copy Section

Currently, there isn't a good way for community members to run acceptance tests.
This is a known problem. We currently have multiple avenues we are exploring to
make running puppet acceptance tests easier for our community. In the meantime,
we apologize for the inconvenience.

For Puppet, Inc. employees Copy Section

If you have access to infrastructure internal to the Puppet, Inc. network, then
the quickest way to get acceptance tests running is with vmpooler.

To test changes that are available on a branch on github.com:

bundle exec rake ci:test:git OPTIONS='--preserve-hosts=always' SHA=ticket/6.0.x/ticketed-work-description RUNTIME_BRANCH=6.0.x FORK=melissa TESTS='tests/path/to/test.rb,tests/other/test.rb'

Where SHA is the branch name, RUNTIME_BRANCH is the agent version stream,
and FORK is the github fork where the branch lives.

To test changes that are available in a puppet-agent package on builds.delivery.puppetlabs.net:

bundle exec rake ci:test:aio OPTIONS='--preserve-hosts=always' SHA=9124b4e81ec0ac6394d3edc67d4ab71866869fd7 TESTS='tests/path/to/test.rb,tests/other/test.rb'

SHA is a sha or tag that exists on builds.delivery.puppetlabs.net/puppet-agent

To rerun a test on the hosts that have already been provisioned, use beaker subcommands:

bundle exec beaker exec tests/path/to/test.rb,tests/other/test.rb

Always clean up after yourself when you are done:

bundle exec beaker destroy

This will remove any provisioned hosts. Only run this once you are done with the
hosts that have been checked out and provisioned for a given run.

Configuration Copy Chapter

Environment Variables Copy Section

A detailed description of the available environment variables can be found by
running bundle exec rake ci:help. This will print a list of both required and
optional environment variables with short descriptions on how they are used.
Please review all of these options as they will impact how your test servers
are provisioned. This rake task is the most up to date source for this
information. Please read through the available variables, their defaults, and
what they do. They may impact your acceptance run in ways you do not expect.

Customizing Test Targets Copy Section

If you are using the vmpooler hypervisor internal to Puppet, Inc. infrastructure,
you can customize the platforms to test on using the HOSTS environment variable.
You'll set the HOSTS environment variable to the host string you want to test,
such as HOSTS=redhat7-64ma-windows2012r2-64a.

For a list of available HOSTS platforms and their exact naming structures,
check the keys listed in beaker hostgenerator. Generally, this string will be in the format
{platform}{version}-{architecture}{role/s}. You will most often use either the
agent (a) or master (m) role, but you can find a list of available roles in
beaker hostgenerator.
Multiple hosts in the string are separated with a dash(-). You must have at
least one agent and at least one master.

Be careful not to confuse the different host string formats. We have different
tools that expect the host string to be in different forms. For example,
packaging_platform is specific to how Vanagon
parses that string.

The Hosts File Copy Section

The rake tasks that run acceptance will by default create a hosts file and
populate it using beaker-hostgenerator using either the HOSTS environment
variable or the default host string (currently redhat7-64ma-windows2012r2-64a).
The automation assumes you are using the vmpooler hypervisor and a vmpooler
instance that is only available to Puppet, Inc. employees. If you want to
customize the hypervisor or the vmpooler instance, you'll need to generate your own
hosts file. You must pass in a valid host string to the beaker-hostgenerator
command. See Customizing Test Targets for more
information on how to construct a valid host string.

To customize the hypervisor, pass in --hypervisor {hypervisor name}. To set
the vmpooler instance, use --global-config pooling_api={vmpooler uri}. Only the
vmpooler hypervisor uses the pooling_api key.

The host string that is passed in is the same that you would use with the
HOSTS environment variable. See Customizing Test Targets
on how to format this string.

To have the automation recognize and use your custom hosts file, you'll need to
set the HOSTS environment variable to the hosts file. In the above example, we
called this file hosts.yaml, so we will set HOSTS to hosts.yaml when running
all future beaker commands or rake tasks to run acceptance tests.

For example, if you were to run this command:

bundle exec beaker-hostgenerator redhat7-64ma-windows2012r2-64a --disable-default-role --osinfo-version 1 --hypervisor vmpooler --global-config pooling_api=http://customvmpooler/ > hosts.yaml

You would generate a file called hosts.yaml that contains something like this:

---
HOSTS:
  redhat7-64-1:
    platform: el-7-x86_64
    packaging_platform: el-7-x86_64
    template: redhat-7-x86_64
    hypervisor: vmpooler
    roles:
    - master
    - agent
  windows2012r2-64-1:
    platform: windows-2012r2-64
    packaging_platform: windows-2012-x64
    ruby_arch: x64
    template: win-2012r2-x86_64
    hypervisor: vmpooler
    roles:
    - agent
CONFIG:
  nfs_server: none
  consoleport: 443
  pooling_api: http://customvmpooler/

We can then run the acceptance tests with:
bundle exec rake ci:test:aio HOSTS=hosts.yaml SHA={sha}

Hypervisor Options Copy Section

The hypervisor dictates where you will be running the acceptance tests. The beaker
hypervisors take care of basic host setup so that you will have a consistent
host environment across every test run. You can find more details on the different
hypervisor options in the beaker repo.

Here, we will focus on vmpooler and docker, as those are the two we use most
often internally. If you use a hypervisor other than abs, vagrant, vmpooler, or
docker, you'll have to add the gem to that hypervisor to Gemfile.local and run
bundle update to install the new gems. You also have the ability to run tests
on a static host.

VMPooler

VMPooler is the default hypervisor we
use. This is only available to Puppet, Inc. employees as it uses internal
infrastructure. If you have access to a similar setup, then you are welcome to
use this option with a few values changed. If you are using the Puppet internal
vmpooler, then you can simply run the acceptance rake tasks. See
Customizing Test Targets about how to use the
HOSTS environment variable to customize the platforms you are running tests on.

To use a different vmpooler instance, use
--global-config pooling_api=http://customvmpooler/ when you use
beaker-hostgenerator to generate hosts.yaml. Make sure you set HOSTS to
the hosts file you just generated so the automation can find that file. See
The Hosts File for more detail on the hosts file.

Docker

To test with the docker hypervisor,
you will want to generate a custom hosts file. You will also mostly likely need
to manually edit the file. See The Hosts File for more
detail on the hosts file.

To create a hosts file with a centos 7 master and a centos 7 agent, we can use
the following beaker-hostgenerator command
bundle exec beaker-hostgenerator centos7-64m-centos7-64a --disable-default-role --osinfo-version 1 --hypervisor docker > hosts.yaml
Which will produce a file called hosts.yaml that contains the following:

---
HOSTS:
  centos7-64-1:
    docker_cmd:
    - "/sbin/init"
    image: centos:7
    platform: centos-7-x86_64
    packaging_platform: el-7-x86_64
    docker_image_commands:
    - cp /bin/true /sbin/agetty
    - yum install -y crontabs initscripts iproute openssl sysvinit-tools tar wget
      which ss
    hypervisor: docker
    roles:
    - master
  centos7-64-2:
    docker_cmd:
    - "/sbin/init"
    image: centos:7
    platform: centos-7-x86_64
    packaging_platform: el-7-x86_64
    docker_image_commands:
    - cp /bin/true /sbin/agetty
    - yum install -y crontabs initscripts iproute openssl sysvinit-tools tar wget
      which ss
    hypervisor: docker
    roles:
    - agent
CONFIG:
  nfs_server: none
  consoleport: 443

Run acceptance tests against pre-built puppet-agent packages with
bundle exec rake ci:test:aio SHA={sha|tag} TESTS=path/to/test.rb HOSTS=hosts.yaml

Note that if you are not running tests against the master branch and you are
installing the latest puppetserver package, you will likely need to set RELEASE_STREAM
to pick up the correct server version. Please see the section on environment variables
for more information.

When you generate your hosts file, beaker-hostgenerator does
its best to populate the values as logically as possible. You will likely want
to update or modify them to suite your needs.

With image, beaker-hostgenerator does its best to guess the most logical
image string based on the platform you are building. For the most part, this
should work without interference, but if you are using a custom docker image or
do not want the default, then you will have to manually update this string. Not
every string beaker-hostgenerator uses to populate this variable will be valid.

docker_image_commands is automatically populated when generating the hosts
file with beaker-hostgenerator. This has already been set for a handful of
host types, but may not be set for all.

• TODO I only tried this once using a docker image that already had puppetserver
  installed as the master host. The image I used took forever to provision,
  so I gave up. If we want to continue down this route, we need to make sure
  the setup steps can check if puppetserver has already been installed so that
  we don't try to install it agian.
• TODO There's something odd with docker_mage_entrypoint versus docker_cmd.
  We should clarify the difference between these two values. I don't quite
  understand what the difference is between them.
• TODO These docker containers have to run in privileged mode (or systemd,
  among possibly other things, won't function as we need them to). This is
  not ideal if you're testing code that affects your OS (ie running docker on
  linux without a docker machine in between the container and your laptop).
  BE CAREFUL

Static Hosts

This is not recommended unless you are familiar with how beaker and
beaker-puppet provision hosts.

To test on a server that's already been spun up or doesn't require a hypervisor,
you should set the name of the host to the FQDN of the server you want to use,
then remove the hypervisor and template settings. This is not recommended, and
you may run into issues with failures or overwritten configuration due to either
beaker provision steps or test provisioning steps.

---
HOSTS:
    azeqdqmk14mvu3g.delivery.puppetlabs.net:
        platform: el-7-x86_64
        packaging_platform: el-7-x86_64
        roles:
          - master

Running Tests Copy Chapter

Testing with pre-built packages Copy Section

bundle exec rake ci:test: SHA={sha|tag}

This is the primary method that we use to run puppet acceptance tests. It
requires puppet-agent packages that have been built with the version of the
puppet code that you want to test. As building packages usually takes quite a
bit of time, this method requires some patience. You are required to set SHA
when running acceptance tests against pre-built packages.

Testing a specific version

If you are testing a specific version, SHA must be set to a value that exists
on the path #{ENV['DEV_BUILDS_URL']}/puppet-agent/#{ENV['SHA']}. Note that
this value corresponds to the puppet-agent package, not to puppet.
DEV_BUILDS_URL defaults to the internal build server that is only accessible
to Puppet, Inc. employees. The method called here depends on information written
to a yaml file in that directory. Though you can override DEV_BUILDS_URL, the
automation here is very specific and likely will not work as you are expecting
it to.

bundle exec rake ci:test:aio SHA=3cfbac6857c10efc5b1e02262cfd7b849bb9c4b2

bundle exec rake ci:test:aio SHA=6.0.5

Testing Nightlies

If you do not have access to internal infrastructure, you can test against
packages that have been made available on nightlies.puppet.com. Currently, you
cannot specify a specific version. Instead, you have to use the latest shipped
package for the release stream you are interested in. To do this, SHA must be
set to latest. If you want to modify the release stream you are testing,
RELEASE_STREAM can be modified. It defaults to puppet which should
correspond to the latest stream available. If you want to modify
RELEASE_STREAM, set it to an available repo, such as puppet5.

bundle exec rake ci:test:aio SHA=latest RELEASE_STREAM=puppet5

Testing with Git Copy Section

bundle exec rake ci:test:git SHA={sha|tag|branch}

From a repo on a git server

Though we primarily run acceptance tests against a built package, it is possible
to run these tests with a git checkout. This is most useful when testing locally
to speed up the feedback cycle.

When testing from a github repo we need to unpack the appropriate
runtime archive
for the platform we are testing on. These pre-built archives are stored on an
internal server, and are currently only available to Puppet, Inc. employees.
With these archives, we get all of the runtime dependencies that are usually
provided as a part of the puppet agent package. This allows us to replicate
the runtime environment produced via a package install for the purpose of
running acceptance tests.

When testing with git, SHA can be set to any git artifact: a long sha, a short
sha, a tag, a branch name, etc. What happens is that we write a gemfile with the
details of the puppet repo, pointing to the artifact referenced with SHA. Then
when we run bundle install on the testing host, bundler grabs puppet from
wherever the gemfile points. If the git artifact referenced is not from the
puppetlabs repo, you can use FORK to point to a different github namespace.
Likewise, if the artifact you want to access is not available on github.com
but a custom git server, you can set SERVER to customize the git uri bundler
pulls from. For more details on these environment variables, run
bundle exec rake ci:help.

As an example, if I have a development branch
(developent/master/major-feature) that I'm working on and it only exists in my
fork of puppet (github.com/joeschmoe/puppet), then I will run

bundle exec rake ci:test:git SHA=developent/master/major-feature FORK=joeschmoe

Please note that any changes you want to test must be pushed up to your github
server. This is how we access the code to be tested.

From a local repo

If you are testing with git and using the docker hypervisor, you can run tests
against the puppet checkout on your local system. You need to update your hosts
file to add mount_folders to the docker host where you want the checkout of
puppet to be available. Here, host_path is the path to puppet on your local
machine. The container_path is where puppet will end up on the docker image,
so you can leave it as /build/puppet. Note that although SHA is required, it
is never used in this workflow. For consistency, I would recommend setting SHA
to your working branch name.

We still need access to our runtime dependencies when testing against a local
git checkout. When we are testing with the docker hypervisor, we assume that the
docker image you are using will have this. As of this writing (Jan. 2019), the
docker image you'll want to use for these tests is not public. The image is
called agent-runtime-{branch}, where {branch} is the branch of puppet you
are testing. This image includes everything we build as a part of the runtime
archive. These components are
normally provided as a part of the puppet agent package.

---
HOSTS:
  debian8-64-1:
    hypervisor: docker
    docker_image_entrypoint: "/sbin/init"
    image: pcr-internal.puppet.net/pe-and-platform/agent-runtime-master:201810110.17.gb5afc66
    platform: debian-8-amd64
    packaging_platform: debian-8-amd64
    docker_image_commands:
      - rm -f /usr/sbin/policy-rc.d
      - systemctl mask [email protected] getty-static.service
      - apt-get update && apt-get install -y cron locales-all net-tools wget
    mount_folders:
      puppet:
        host_path: ~/puppet
        container_path: /build/puppet
    roles:
      - agent

For more details on testing with docker, see the docker section.
Remember that HOSTS must be set to your hosts file for the automation to honor
it.

Testing with Gems Copy Section

Currently, running acceptance tests with gems is not working.

bundle exec rake ci:test:gem

Rerunning Failed Tests Copy Section

The rake tasks we use here take advantage of a newer feature in beaker that gives us quite a bit of flexibility. We take advantage of beaker subcommands. Subcommands are individual beaker invocations that are used to run the different stages of running tests: provisioning, pre-suite setup, tests, etc. We do this by writing state to the file .beaker/subcommand_options.yaml. With each new invocation of a subcommand, beaker will check for this file and load the contents if the file exists. The important thing about this feature is that you can rerun tests without going through the entire provisioning process every time.

To ensure your hosts aren't cleaned up after a run, set OPTIONS='--preserve-hosts=always'. With this set, we can rerun a failed test using the infrastructure beaker has already provisioned.

bundle exec rake ci:test:aio OPTIONS='--preserve-hosts=always' SHA=6.0.5

If this run fails because a small handful of tests fail, you can rerun only those tests that failed. For example, assume that tests/resource/package/yum.rb and tests/node/check_woy_cache_works.rb both had failing tests. you can run

bundle exec beaker exec tests/resource/package/yum.rb,tests/node/check_woy_cache_works.rb

This should work regardless of which hypervisor or testing method you are using.

Writing Tests Copy Chapter

Read more about writing beaker tests in beaker. Check out the tutorials section
and how to write a quick test

Getting Help Copy Chapter

On the web Copy Section

• Puppet help messageboard
• General GitHub documentation

On chat Copy Section

• Slack (slack.puppet.com) #testing, #puppet-dev, #windows

File: api/docs/http_api_index.md Copy Chapter

A Puppet server provides several services via HTTP API, and the Puppet
agent application uses those services to resolve a node's credentials, retrieve
a configuration catalog, retrieve file data, and submit reports.

In general, these APIs aren't designed for use by tools other than Puppet agent.
This is gradually changing, although we expect external use of these APIs to
remain low for the foreseeable future. The server ignores any parameters it isn't expecting.

V1/V2 HTTP APIs (Removed) Copy Chapter

The V1 and V2 APIs were removed in Puppet 4.0.0. The routes that were previously
under / or /v2.0 can now be found under the /puppet/v3
API or /puppet-ca/v1 API.

Starting with version 2.1, the Puppet Server 2.x series provides both the
current and previous API endpoints, and can serve nodes running Puppet agent 3.x
and 4.x. However, Rack masters, WEBrick masters, and Puppet Server 2.0 cannot
serve nodes running Puppet 3.x.

Puppet and Puppet CA APIs Copy Chapter

Beginning with Puppet 4, Puppet's HTTP API has been split into two APIs, which
are versioned separately. There is now an API for configuration-related services
and a separate one for the certificate authority (CA).

All configuration endpoints are prefixed with /puppet, while all CA endpoints are
prefixed with /puppet-ca. All endpoints are explicitly versioned: the prefix
is always immediately followed by a string such as /v3 (a directory separator,
the letter v, and the version number of the API).

Authorization Copy Section

As of Puppet 7, support for legacy auth.conf is removed. Puppet Server 7
enforces all authorization using its auth.conf. See
https://puppet.com/docs/puppetserver/latest/config_file_auth.html for more
details.

Puppet V3 HTTP API Copy Chapter

The Puppet agent application uses several network services to manage systems.
These services are all grouped under the /puppet API. Other tools can access
these services and use the Puppet server's data for other purposes.

The V3 API contains endpoints of two types: those that are based on dispatching
to Puppet's internal "indirector" framework, and those that are not (namely the
environment endpoints).

Every HTTP endpoint that dispatches to the indirector follows the form:
/puppet/v3/:indirection/:key?environment=:environment where:

• :environment is the name of the environment that should be in effect for
  the request. Not all endpoints need an environment, but the query
  parameter must always be specified.
• :indirection is the indirection to dispatch the request to.
• :key is the "key" portion of the indirection call.

Using this API requires significant understanding of how Puppet's internal
services are structured, but the following documents attempt to specify what is
available and how to interact with it.

Configuration Management Services Copy Section

These services are all directly used by the Puppet agent application, in order
to manage the configuration of a node.

These endpoints accept payload formats formatted as JSON (MIME type
application/json) except for File Content and File Bucket File which
always use application/octet-stream.

• Facts
• Catalog
• Node
• File Bucket File
• File Content
• File Metadata
• Report

Informational Services Copy Section

These services are not directly used by Puppet agent, but may be used by other
tools.

• Status

Environments Endpoint Copy Section

The /puppet/v3/environments endpoint is different as it will only accept payloads
formatted as JSON and respond with JSON (MIME type of application/json).

• Environments

Puppet Server-specific endpoints Copy Section

Puppet Server adds additional /puppet/v3/ endpoints:

• Static File Content
• Environment Classes

Error Responses

The environments endpoint will respond to error conditions in a uniform manner
and use standard HTTP response code to signify those errors.

• When the client submits a malformed request, the API will return a 400 Bad
  Request response.
• When the client is not authorized, the API will return a 403 Not Authorized
  response.
• When the client attempts to use an HTTP method that is not permissible for
  the endpoint, the API will return a 405 Method Not Allowed response.
• When the client asks for a response in a format other than JSON, the API will
  return a 406 Unacceptable response.
• When the server encounters an unexpected error during the handling of a
  request, it will return a 500 Server Error response.
• When the server is unable to find an endpoint handler for an http request,
  it will return a 404 Not Found response

All error responses will contain a body, except when it is a HEAD request. The
error responses will uniformly be a JSON object with the following properties:

• message: (String) A human readable message explaining the error.
• issue_kind: (String) A unique label to identify the error class.

A JSON schema for the error objects is also available.

CA V1 HTTP API Copy Chapter

The certificate authority (CA) API contains all of the endpoints supporting Puppet's public key infrastructure (PKI) system. This endpoint is now handled entirely through Puppet Server. See Puppet Server's HTTP API docs for detailed information.

Serialization Formats Copy Chapter

Puppet sends messages using JSON or as binary data. Not all
REST services support all of the formats.

• JSON
• PSON was supported in earlier versions of Puppet, but is no longer for performance reasons.

YAML was supported in earlier versions of Puppet, but is no longer for security reasons.

File: api/docs/http_catalog.md Copy Chapter

Catalog

The catalog endpoint returns a catalog for the specified node name given the provided facts.

Find Copy Chapter

Retrieve a catalog.

POST /puppet/v3/catalog/:nodename
GET /puppet/v3/catalog/:nodename?environment=:environment

Supported HTTP Methods Copy Section

POST, GET

Supported Response Formats Copy Section

application/json

Notes Copy Section

The POST and GET methods are functionally equivalent. Both provide the 3 parameters specified below: the POST in the
request body, the GET in the query string.

Puppet originally used GET; POST was added because some web servers have a maximum URI length of
1024 bytes (which is easily exceeded with the facts parameter).

The examples below use the POST method.

Parameters Copy Section

Four parameters should be provided to the POST or GET:

• environment: the environment name.
• facts_format: must be application/json.
• facts: serialized JSON of the facts hash. Since facts can contain &, which
  is also the HTTP query parameter delimiter, facts are doubly-escaped.
• transaction_uuid: a transaction uuid identifying the entire transaction (shows up in the report as well).

Two optional parameters are required for static catalogs:

• static_catalog: a boolean requesting a
  static catalog if available; should always
  be true.
• checksum_type: a dot-separated list of checksum types supported by the agent, for use in file resources of a static
  catalog. The order signifies preference, highest first.

Optional parameters that may be provided to the POST or GET:

• configured_environment: the environment configured on the client. May be
  provided to notify an ENC that the client requested a specific environment
  which might differ from what the client believes is its current environment.
• job_id: which orchestration job triggered this catalog request.

Example Response Copy Section

Catalog found

POST /puppet/v3/catalog/elmo.mydomain.com

environment=env&configured_environment=canary_env&facts_format=application%2Fjson&facts=%257B%2522name%2522%253A%2522elmo.mydomain.com%2522%252C%2522values%2522%253A%257B%2522architecture%2522%253A%2522x86_64%2522%257D%257D&transaction_uuid=aff261a2-1a34-4647-8c20-ff662ec11c4c

HTTP 200 OK
Content-Type: application/json

{
  "tags": [
    "settings",
    "multi_param_class",
    "class"
  ],
  "name": "elmo.mydomain.com",
  "version": 1377473054,
  "code_id": null,
  "catalog_uuid": "827a74c8-cf98-44da-9ff7-18c5e4bee41e",
  "catalog_format": 1,
  "environment": "production",
  "resources": [
    {
      "type": "Stage",
      "title": "main",
      "tags": [
        "stage"
      ],
      "exported": false,
      "parameters": {
        "name": "main"
      }
    },
    {
      "type": "Class",
      "title": "Settings",
      "tags": [
        "class",
        "settings"
      ],
      "exported": false
    },
    {
      "type": "Class",
      "title": "main",
      "tags": [
        "class"
      ],
      "exported": false,
      "parameters": {
        "name": "main"
      }
    },
    {
      "type": "Class",
      "title": "Multi_param_class",
      "tags": [
        "class",
        "multi_param_class"
      ],
      "line": 10,
      "exported": false,
      "parameters": {
        "one": "hello",
        "two": "world"
      }
    },
    {
      "type": "Notify",
      "title": "foo",
      "tags": [
        "notify",
        "foo",
        "class",
        "multi_param_class"
      ],
      "line": 4,
      "exported": false,
      "parameters": {
        "message": "One is hello, two is world"
      }
    }
  ],
  "edges": [
    {
      "source": "Stage[main]",
      "target": "Class[Settings]"
    },
    {
      "source": "Stage[main]",
      "target": "Class[main]"
    },
    {
      "source": "Stage[main]",
      "target": "Class[Multi_param_class]"
    },
    {
      "source": "Class[Multi_param_class]",
      "target": "Notify[foo]"
    }
  ],
  "classes": [
    "settings",
    "multi_param_class"
  ]
}

Static Catalog found

POST /puppet/v3/catalog/elmo.mydomain.com

environment=env&configured_environment=canary_env&facts_format=application%2Fjson&facts=%7B%22name%22%3A%22elmo.mydomain.com%22%2C%22values%22%3A%7B%22architecture%22%3A%22x86_64%22%7D&transaction_uuid=aff261a2-1a34-4647-8c20-ff662ec11c4c&static_catalog=true&checksum_type=sha256.md5

HTTP 200 OK
Content-Type: application/json

{
  "tags": [
    "settings",
    "multi_param_class",
    "class"
  ],
  "name": "elmo.mydomain.com",
  "version": 1377473054,
  "code_id": "arbitrary_code_id_string",
  "catalog_uuid": "827a74c8-cf98-44da-9ff7-18c5e4bee41e",
  "catalog_format": 1,
  "environment": "production",
  "resources": [
    {
      "type": "Stage",
      "title": "main",
      "tags": [
        "stage"
      ],
      "exported": false,
      "parameters": {
        "name": "main"
      }
    },
    {
      "type": "Class",
      "title": "Settings",
      "tags": [
        "class",
        "settings"
      ],
      "exported": false
    },
    {
      "type": "Class",
      "title": "main",
      "tags": [
        "class"
      ],
      "exported": false,
      "parameters": {
        "name": "main"
      }
    },
    {
      "type": "Class",
      "title": "Multi_param_class",
      "tags": [
        "class",
        "multi_param_class"
      ],
      "line": 10,
      "exported": false,
      "parameters": {
        "one": "hello",
        "two": "world"
      }
    },
    {
      "type": "Notify",
      "title": "foo",
      "tags": [
        "notify",
        "foo",
        "class",
        "multi_param_class"
      ],
      "line": 4,
      "exported": false,
      "parameters": {
        "message": "One is hello, two is world"
      }
    },
    {
      "type": "File",
      "title": "/tmp/foo",
      "tags": [
        "file",
        "class"
      ],
      "line": 12,
      "exported": false,
      "parameters": {
        "ensure": "file",
        "source": "puppet:///modules/a_module/foo"
      }
    },
    {
      "type": "File",
      "title": "/tmp/bar",
      "tags": [
        "file",
        "class"
      ],
      "line": 16,
      "exported": false,
      "parameters": {
        "ensure": "present",
        "source": "puppet:///modules/a_module/bar",
        "recurse", "true"
      }
  ],
  "edges": [
    {
      "source": "Stage[main]",
      "target": "Class[Settings]"
    },
    {
      "source": "Stage[main]",
      "target": "Class[main]"
    },
    {
      "source": "Stage[main]",
      "target": "Class[Multi_param_class]"
    },
    {
      "source": "Class[Multi_param_class]",
      "target": "Notify[foo]"
    },
    {
      "source": "Class[Main]",
      "target": "File[/tmp/foo]"
    }
  ],
  "classes": [
    "settings",
    "multi_param_class"
  ]
  "metadata": {
    "/tmp/foo": {
      "checksum": {
        "type": "sha256",
        "value": "{sha256}5891b5b522d5df086d0ff0b110fbd9d21bb4fc7163af34d08286a2e846f6be03"
      },
      "content_uri": "puppet:///modules/a_module/files/foo",
      "destination": null,
      "group": 20,
      "links": "manage",
      "mode": 420,
      "owner": 501,
      "path": "/etc/puppetlabs/code/environments/production/modules/a_module/files/foo.txt",
      "relative_path": null,
      "source": "puppet:///modules/a_module/foo",
      "type": "file"
    }
  },
  "recursive_metadata": {
    "/tmp/bar": {
      "puppet:///modules/a_module/bar": [
        {
          "checksum": {
            "type": "ctime",
            "value": "{ctime}2016-02-19 17:38:36 -0800"
          },
          "content_uri": "puppet:///modules/a_module/files/bar",
          "destination": null,
          "group": 20,
          "links": "manage",
          "mode": 420,
          "owner": 501,
          "path": "/etc/puppetlabs/code/environments/production/modules/a_module/files/bar",
          "relative_path": ".",
          "source": null,
          "type": "directory"
        },
        {
          "checksum": {
            "type": "sha256",
            "value": "{sha256}962dbd7362c34a20baac8afd13fba734d3d51cc2944477d96ee05a730e5edcb7"
          },
          "content_uri": "puppet:///modules/a_module/files/bar/baz",
          "destination": null,
          "group": 20,
          "links": "manage",
          "mode": 420,
          "owner": 501,
          "path": "/etc/puppetlabs/code/environments/production/modules/a_module/files/bar",
          "relative_path": "baz",
          "source": null,
          "type": "file"
        }
      ]
    }
  }
}

Schema Copy Chapter

In the POST request body (or the GET query), the facts parameter should conform
to the facts schema.

A catalog response body conforms to
the catalog schema.

File: api/docs/http_certificate.md Copy Chapter

Certificate

The certificate endpoint returns the certificate for the specified name,
which might be either a standard certname or ca.

Under Puppet Server's CA service, the environment parameter is ignored and can
be omitted. Under a Rack or WEBrick Puppet master, environment is required and
must be a valid environment, but it has no effect on the response.

Find Copy Chapter

Get a certificate.

GET /puppet-ca/v1/certificate/:nodename?environment=:environment

Supported HTTP Methods Copy Section

GET

Supported Response Formats Copy Section

text/plain

The returned certificate is always in the .pem format.

Parameters Copy Section

None

Responses Copy Section

Certificate found

GET /puppet-ca/v1/certificate/elmo.mydomain.com?environment=env

HTTP 200 OK
Content-Type: text/plain

-----BEGIN CERTIFICATE-----
MIIFujCCA6KgAwIBAgIBATANBgkqhkiG9w0BAQsFADBiMWAwXgYDVQQDDFdQdXBw
ZXQgQ0EgZ2VuZXJhdGVkIG9uIGRoY3A1MC5reWxvLmJhY2tsaW5lLnB1cHBldGxh
YnMubmV0IGF0IDIwMTMtMDYtMjQgMTY6MzA6MTcgLTA3MDAwHhcNMTMwNjIzMjMz
MDE5WhcNMTgwNjIzMjMzMDE5WjBiMWAwXgYDVQQDDFdQdXBwZXQgQ0EgZ2VuZXJh
dGVkIG9uIGRoY3A1MC5reWxvLmJhY2tsaW5lLnB1cHBldGxhYnMubmV0IGF0IDIw
MTMtMDYtMjQgMTY6MzA6MTcgLTA3MDAwggIiMA0GCSqGSIb3DQEBAQUAA4ICDwAw
ggIKAoICAQDABq1lmzccjuRmnCdXvTmdeXJGb9S8r8+I+G6fkHTa1WKDSob9PZpS
eXJtanbl0zNws9yBt1Dko2zhKDKctBRWf5CT42nDxBZPY7SaD7KaCzb07g9wfWgU
BOb/6smyl/iySEmQzzFLRgZbo5A9WLiy/UdyQim1faakevRme2Xi/l/i0TKbpu27
DhCS+E8aC8Bvaj0ph0T+TzYphTR76pP5Kps6G7Jyk/HFYrVXnY44X2PEt2mgkEXp
xHCbU+qCFMtTLMG+ZArA/noM3I/O6W5LhLSzApjut/M7UdMlpZ45PGDrsvf2R306
NcOh+zbbkhxuIaGqaxeaenYzbOlA3gXhZvYaV6EKjXNtm7BslpsvhLi0U+CWyb3C
qRkpex0MgxJgxoqViJ4TDVA+EmztOnK86+G4HGeJqTPQloYO/Td1wMT1Txh9T5Ue
Wctw/g+4o22EyJQRo+vxxzHNRIfe7EHAerMUtLT5u9MJeQb9N1iUR2ATNAN+QiB2
KEqyc9eMapK6QUZFV23Xvbdup1WCrgsWXBqyRWKV7x0sc9Wv8RMRKEFYaBeHEVXU
m0hGgF34Z8Rzphq2H1FjkLD+xbtGOjrA1Mb2De81Hfvrf18497X5UMPtsuzOt/XU
PHbbSCy+05J7VNZ/gaiGqgpHfcG5yiqCdj1LIzhFuuvm+fADPxK38wIDAQABo3sw
eTA3BglghkgBhvhCAQ0EKhYoUHVwcGV0IFJ1YnkvT3BlblNTTCBJbnRlcm5hbCBD
ZXJ0aWZpY2F0ZTAOBgNVHQ8BAf8EBAMCAQYwDwYDVR0TAQH/BAUwAwEB/zAdBgNV
HQ4EFgQUEhn/MqSDtuxg12klWosCGenxf1cwDQYJKoZIhvcNAQELBQADggIBAH1G
L3FG/keKlGqs70PxxvR1wCo4VM3K/C+5uxnzm1MHEAd96nhtwE6YSkUe+XgDiXfC
+NXS2C4TeTQAEo6grREapWDjhJvrhrgqTZmb4lTKzb91II3/VGYzG5UXxID262zy
QLoX/IBN/xDJ5ds0wF2adUbnHUssEGGljgngewH/7kjeW/L5iL+USXZnKHPSggjM
RAEjlucE/rDqDNoxhOS4K2PjseFm7krW4cZ0gNmxdrhc7OhmJ56dH92F4M9jn7Qy
EqxWB304U/aMcO3NJxTQc7AreL/pUtjtI6hxM4miHbjSh6RfNBqhzRyJvxA6gc6g
m3kumdw04KZFSs/6fPFFbI60i5K+vioB4CnUWpj+3Z+OnDEvhQJEACR1JC8A67Ih
x+GDlbHLU1BWonwZzSMJz+ABXV3dwIrOSFHI0UmDXg+cIdZ+SaL93qMjUVU4v9nu
gR9yJGMqNuzLjgfbD/KGCEEAITKBwPvCVd//OMlWVrXr7vvt+yo6STIlTJxABJDp
CSLyHUtT++CsPXsPADxgRctpIbh1eMFEivkK9Oy+W/CZYIZnARVysUpMWg7TkXqx
mSCXy9ZXLWqU/ssVhbLS9vFVa5pvxcyfiRpsFg0XZsx8mnZP6OaWcL8FjF+/NwNP
tg1+DuYTn+d54OHi/GZEnvutgrDZyrJDrrb/Czm9
-----END CERTIFICATE-----

Certificate not found

GET /puppet-ca/v1/certificate/certificate_does_not_exist?environment=env

HTTP 404 Not Found
Content-Type: text/plain

Not Found: Could not find certificate certificate_does_not_exist

No Certificate name given

GET /puppet-ca/v1/certificate?environment=env

HTTP/1.1 400 Bad Request
Content-Type: text/plain

No request key specified in /puppet-ca/v1/certificate

Master is not a CA

GET /puppet/v1/certificate/valid_certificate?environment=env

HTTP/1.1 400 Bad Request
Content-Type: text/plain

this master is not a CA

Schema Copy Chapter

A certificate response body is not structured data according to any standard scheme such as
json/pson/yaml, so no schema is applicable.

File: api/docs/http_certificate_request.md Copy Chapter

Certificate Request

The certificate_request endpoint submits a Certificate Signing Request (CSR)
to the master. The master must be configured to be a CA. The returned
CSR is always in the .pem format.

Under Puppet Server's CA service, the environment parameter is ignored and can
be omitted. Under a Rack or WEBrick Puppet master, environment is required and
must be a valid environment, but it has no effect on the response.

Find Copy Chapter

Get a submitted CSR

GET /puppet-ca/v1/certificate_request/:nodename?environment=:environment
Accept: text/plain

Save Copy Chapter

Submit a CSR

PUT /puppet-ca/v1/certificate_request/:nodename?environment=:environment
Content-Type: text/plain

Note: The :nodename must match the Common Name on the submitted CSR.

Note: Although the Content-Type is sent as text/plain the content is
specifically a CSR in PEM format.

Search Copy Chapter

Note: The plural certificate_requests endpoint is a legacy feature. Puppet
Server doesn't support it, and we don't plan to add support in the future.

List submitted CSRs

GET /puppet-ca/v1/certificate_requests/:ignored_pattern?environment=:environment
Accept: text/plain

The :ignored_pattern parameter is not used, but must still be provided.

Destroy Copy Chapter

Delete a submitted CSR

DELETE /puppet-ca/v1/certificate_request/:nodename?environment=:environment
Accept: text/plain

Supported HTTP Methods Copy Section

The default configuration only allows requests that result in a Find and a
Save. You need to modify Puppet Server's auth.conf in order to allow clients to use Search and
Destroy actions. It is not recommended that you change the default settings.

GET, PUT, DELETE

Supported Response Formats Copy Section

text/plain

The returned CSR is always in the .pem format.

Parameters Copy Section

None

Examples Copy Section

CSR found

GET /puppet-ca/v1/certificate_request/agency?environment=env

HTTP/1.1 200 OK
Content-Type: text/plain

-----BEGIN CERTIFICATE REQUEST-----
MIIBnzCCAQwCAQAwYzELMAkGA1UEBhMCVUsxDzANBgNVBAgTBkxvbmRvbjEPMA0G
A1UEBxMGTG9uZG9uMSEwHwYDVQQKExhJbnRlcm5ldCBXaWRnaXRzIFB0eSBMdGQx
DzANBgNVBAMTBmFnZW5jeTCBnzANBgkqhkiG9w0BAQEFAAOBjQAwgYkCgYEAxSCr
FKUKjVGFPuQ0iGM9mZKw94sOIgGohqrHH743kPvjsId3d38Qk+H+1DbVf42bQY0W
kAVcwNDqmBnx0lOtQ0oeGnbbwlJFjhqXr8jFEljPrc9S2/IIILDf/FeYWw9lRiOV
LoU6ZfCIBfq6v4D4KX3utRbOoELNyBeT6VA1ufMCAwEAAaAAMAkGBSsOAwIPBQAD
gYEAno7O1jkR56TNMe1Cw/eyQUIaniG22+0kmoftjlcMYZ/IKCOz+HRgnDtBPf8j
O5nt0PQN8YClW7Xx2U8ZTvBXn/UEKMtCBkbF+SULiayxPgfyKy/axinfutEChnHS
ZtUMUBLlh+gGFqOuH69979SJ2QmQC6FNomTkYI7FOHD/TG0=
-----END CERTIFICATE REQUEST-----

CSR not found

GET /puppet-ca/v1/certificate_request/does_not_exist?environment=env

HTTP/1.1 404 Not Found
Content-Type: text/plain

Not Found: Could not find certificate_request does_not_exist

No node name given

GET /puppet-ca/v1/certificate_request?environment=env

HTTP/1.1 400 Bad Request
Content-Type: text/plain

No request key specified in /puppet-ca/v1/certificate_request

Delete a CSR that exists

DELETE /puppet-ca/v1/certificate_request/agency?environment=production
Accept: s

HTTP/1.1 200 OK
Content-Type: text/plain

1

Delete a CSR that does not exists

DELETE /puppet-ca/v1/certificate_request/missing?environment=production
Accept: s

HTTP/1.1 200 OK
Content-Type: text/plain

false

Retrieve all CSRs

GET /puppet-ca/v1/certificate_requests/ignored?environment=production
 Accept: s

 HTTP/1.1 200 OK
 Content-Type: text/plain

 -----BEGIN CERTIFICATE REQUEST-----
 MIIBnzCCAQwCAQAwYzELMAkGA1UEBhMCVUsxDzANBgNVBAgTBkxvbmRvbjEPMA0G
 A1UEBxMGTG9uZG9uMSEwHwYDVQQKExhJbnRlcm5ldCBXaWRnaXRzIFB0eSBMdGQx
 DzANBgNVBAMTBmFnZW5jeTCBnzANBgkqhkiG9w0BAQEFAAOBjQAwgYkCgYEAxSCr
 FKUKjVGFPuQ0iGM9mZKw94sOIgGohqrHH743kPvjsId3d38Qk+H+1DbVf42bQY0W
 kAVcwNDqmBnx0lOtQ0oeGnbbwlJFjhqXr8jFEljPrc9S2/IIILDf/FeYWw9lRiOV
 LoU6ZfCIBfq6v4D4KX3utRbOoELNyBeT6VA1ufMCAwEAAaAAMAkGBSsOAwIPBQAD
 gYEAno7O1jkR56TNMe1Cw/eyQUIaniG22+0kmoftjlcMYZ/IKCOz+HRgnDtBPf8j
 O5nt0PQN8YClW7Xx2U8ZTvBXn/UEKMtCBkbF+SULiayxPgfyKy/axinfutEChnHS
 ZtUMUBLlh+gGFqOuH69979SJ2QmQC6FNomTkYI7FOHD/TG0=
 -----END CERTIFICATE REQUEST-----

 ---
 -----BEGIN CERTIFICATE REQUEST-----
 MIIBnjCCAQsCAQAwYjELMAkGA1UEBhMCVUsxDzANBgNVBAgTBkxvbmRvbjEPMA0G
 A1UEBxMGTG9uZG9uMSEwHwYDVQQKExhJbnRlcm5ldCBXaWRnaXRzIFB0eSBMdGQx
 DjAMBgNVBAMTBWFnZW50MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQC1tucK
 enT1CkDPgsCU/0e2cbzRsiKF8yHH7+ntF6Q3d9ZCaZWJ00mj0+YmiYrnum+KAikE
 45Iaf9vaUV3CPsDVrUPOI8kYehiv868ZhP3nxblE6iuNBK+Fdv9GN/vKQrmL5iRE
 bIrOM3/lxpS7SpidGdA6EIVlS3604bwLY4xHNQIDAQABoAAwCQYFKw4DAg8FAAOB
 gQAXH0YFuidPqB6P2MyPEEGZ3rzozINBx/oXvGptXI60Zy5mgH6iAkrZfi57pEzP
 jFoO2JRaFxTJC1FVpc4zR1K6sq4h3fIMwqppJRX+5wJNKyhU61eY2gR2O/rAJzw4
 wcUKf9JhoE7/p1cUulIIIq7t/ibCvf0LYSFwGqTwGqN2TQ==
 -----END CERTIFICATE REQUEST-----

The CSR PEMs are separated by "\n---\n"

Schema Copy Chapter

A certificate_request response body is not structured data according to any
standard scheme such as json/pson/yaml, so no schema is applicable.

File: api/docs/http_certificate_revocation_list.md Copy Chapter

Certificate Revocation List

The certificate_revocation_list endpoint retrieves a Certificate Revocation List (CRL)
from the master. The master must be configured to be a CA. The returned
CRL is always in the .pem format.

Under Puppet Server's CA service, the environment parameter is ignored and can
be omitted. Under a Rack or WEBrick Puppet master, environment is required and
must be a valid environment, but it has no effect on the response.

The :nodename should always be ca, due to Puppet Server's default
auth.conf. (You can use a different :nodename if you change the auth rules,
but it will have no effect on the response.)

Find Copy Chapter

Get the submitted CRL

GET /puppet-ca/v1/certificate_revocation_list/:nodename?environment=:environment
Accept: text/plain

Supported HTTP Methods Copy Section

GET

Supported Response Formats Copy Section

text/plain

The returned CRL is always in the .pem format.

Parameters Copy Section

None

Examples Copy Section

Since the returned CRL always looks similar to the human eye, the successful examples are each followed by an openssl
decoding of the CRL PEM file.

Empty revocation list

GET /puppet-ca/v1/certificate_revocation_list/ca?environment=env

HTTP/1.1 200 OK
Content-Type: text/plain

-----BEGIN X509 CRL-----
MIICdzBhAgEBMA0GCSqGSIb3DQEBBQUAMB8xHTAbBgNVBAMMFFB1cHBldCBDQTog
bG9jYWxob3N0Fw0xMzA3MTYyMDQ4NDJaFw0xODA3MTUyMDQ4NDNaoA4wDDAKBgNV
HRQEAwIBADANBgkqhkiG9w0BAQUFAAOCAgEAqyBJOy3dtCOcrb0Fu7ZOOiDQnarg
IzXUV/ug1dauPEVyURLNNr+CJrr89QZnU/71lqgpWTN/J47mO/lffMSPjmINE+ng
XzOffm0qCG2+gNyaOBOdEmQTLdHPIXvcm7T+wEqc7XFW2tjEdpEubZgweruU/+DB
RX6/PhFbalQ0bKcMeFLzLAD4mmtBaQCJISmUUFWx1pyCS6pgBtQ1bNy3PJPN2PNW
YpDf3DNZ16vrAJ4a4SzXLXCoONw0MGxZcS6/hctJ75Vz+dTMrArKwckytWgQS/5e
c/1/wlMZn4xlho+EcIPMPfCB5hW1qzGU2WjUakTVxzF4goamnfFuKbHKEoXVOo9C
3dEQ9un4Uyd1xHxj8WvQck79In5/S2l9hdqp4eud4BaYB6tNRKxlUntSCvCNriR2
wrDNsMuQ5+KJReG51vM0OzzKmlScgIHaqbVeNFZI9X6TpsO2bLEZX2xyqKw4xrre
OIEZRoJrmX3VQ/4u9hj14Qbt72/khYo6z/Fckc5zVD+dW4fjP2ztVTSPzBqIK3+H
zAgewYW6cJ6Aan8GSl3IfRqj6WlOubWj8Gr1U0dOE7SkBX6w/X61uqsHrOyg/E/Z
0Wcz/V+W5iZxa4Spm0x4sfpNzf/bNmjTe4M2MXyn/hXx5MdHf/HZdhOs/lzwKUGL
kEwcy38d6hYtUjs=
-----END X509 CRL-----

> openssl crl -inform PEM -in empty.crl -text -noout
Certificate Revocation List (CRL):
        Version 2 (0x1)
        Signature Algorithm: sha1WithRSAEncryption
        Issuer: /CN=Puppet CA: localhost
        Last Update: Jul 16 20:48:42 2013 GMT
        Next Update: Jul 15 20:48:43 2018 GMT
        CRL extensions:
            X509v3 CRL Number:
                0
No Revoked Certificates.
    Signature Algorithm: sha1WithRSAEncryption
        ab:20:49:3b:2d:dd:b4:23:9c:ad:bd:05:bb:b6:4e:3a:20:d0:
        9d:aa:e0:23:35:d4:57:fb:a0:d5:d6:ae:3c:45:72:51:12:cd:
        36:bf:82:26:ba:fc:f5:06:67:53:fe:f5:96:a8:29:59:33:7f:
        27:8e:e6:3b:f9:5f:7c:c4:8f:8e:62:0d:13:e9:e0:5f:33:9f:
        7e:6d:2a:08:6d:be:80:dc:9a:38:13:9d:12:64:13:2d:d1:cf:
        21:7b:dc:9b:b4:fe:c0:4a:9c:ed:71:56:da:d8:c4:76:91:2e:
        6d:98:30:7a:bb:94:ff:e0:c1:45:7e:bf:3e:11:5b:6a:54:34:
        6c:a7:0c:78:52:f3:2c:00:f8:9a:6b:41:69:00:89:21:29:94:
        50:55:b1:d6:9c:82:4b:aa:60:06:d4:35:6c:dc:b7:3c:93:cd:
        d8:f3:56:62:90:df:dc:33:59:d7:ab:eb:00:9e:1a:e1:2c:d7:
        2d:70:a8:38:dc:34:30:6c:59:71:2e:bf:85:cb:49:ef:95:73:
        f9:d4:cc:ac:0a:ca:c1:c9:32:b5:68:10:4b:fe:5e:73:fd:7f:
        c2:53:19:9f:8c:65:86:8f:84:70:83:cc:3d:f0:81:e6:15:b5:
        ab:31:94:d9:68:d4:6a:44:d5:c7:31:78:82:86:a6:9d:f1:6e:
        29:b1:ca:12:85:d5:3a:8f:42:dd:d1:10:f6:e9:f8:53:27:75:
        c4:7c:63:f1:6b:d0:72:4e:fd:22:7e:7f:4b:69:7d:85:da:a9:
        e1:eb:9d:e0:16:98:07:ab:4d:44:ac:65:52:7b:52:0a:f0:8d:
        ae:24:76:c2:b0:cd:b0:cb:90:e7:e2:89:45:e1:b9:d6:f3:34:
        3b:3c:ca:9a:54:9c:80:81:da:a9:b5:5e:34:56:48:f5:7e:93:
        a6:c3:b6:6c:b1:19:5f:6c:72:a8:ac:38:c6:ba:de:38:81:19:
        46:82:6b:99:7d:d5:43:fe:2e:f6:18:f5:e1:06:ed:ef:6f:e4:
        85:8a:3a:cf:f1:5c:91:ce:73:54:3f:9d:5b:87:e3:3f:6c:ed:
        55:34:8f:cc:1a:88:2b:7f:87:cc:08:1e:c1:85:ba:70:9e:80:
        6a:7f:06:4a:5d:c8:7d:1a:a3:e9:69:4e:b9:b5:a3:f0:6a:f5:
        53:47:4e:13:b4:a4:05:7e:b0:fd:7e:b5:ba:ab:07:ac:ec:a0:
        fc:4f:d9:d1:67:33:fd:5f:96:e6:26:71:6b:84:a9:9b:4c:78:
        b1:fa:4d:cd:ff:db:36:68:d3:7b:83:36:31:7c:a7:fe:15:f1:
        e4:c7:47:7f:f1:d9:76:13:ac:fe:5c:f0:29:41:8b:90:4c:1c:
        cb:7f:1d:ea:16:2d:52:3b

One-item revocation list

GET /puppet-ca/v1/certificate_revocation_list/ca?environment=env

HTTP/1.1 200 OK
Content-Type: text/plain

-----BEGIN X509 CRL-----
MIICnDCBhQIBATANBgkqhkiG9w0BAQUFADAfMR0wGwYDVQQDDBRQdXBwZXQgQ0E6
IGxvY2FsaG9zdBcNMTMxMDA3MTk0ODQwWhcNMTgxMDA2MTk0ODQxWjAiMCACAQUX
DTEzMTAwNzE5NDg0MVowDDAKBgNVHRUEAwoBAaAOMAwwCgYDVR0UBAMCAQEwDQYJ
KoZIhvcNAQEFBQADggIBALrh49WNdmrJOPCRntD1nxCObmqZgl8ZwTv7TO9VkmCG
Ksvo8zR2aTIOH9VUKqWrE0squhtFJXl8dxL4PR1RiLbmhO7dp+NHdu8ejTQpoOTp
h69xbQFT3oHcIdn2cBGrLJQcZgXsiswT0KJ8nuw6eDO93yXDrguSUdou99M99wTw
2nn1kUQKW9b0vUI7t2ADF5U8/DES+1IrvBq2IEHmg4+ekZRCxeJMuqd1R13gymcJ
osSPbRgIjCli6zD3aK4Nq5OMMpVLV/VVPwyQb4GwW4Wj5iyNAp8d/EAqtZ21ZHUi
nvuXmRtUWHJwfi40D5T2GQXxuUjB4pnh8cFq7f89iUvqoCwFo7nRIacrrweNFMYD
GxVJVMfz4PkP66ckIPQ5Uuey92dg5p2w4b2cp8NstxMdgcc3KAF483ItKA8uIDuU
1dbzw1v2k5qUjoImueHwKolbLmPyYmvFp7hbnV+WpFbvGjyIfW3BMankDEv4ig0L
MCw6n2GKv1hSWM6Mrk8Ja1yYOFLsjI0RoVCZsf1iNiRT28haldXVTPyNtct9mGAv
6az5W/nyixIPrrHubTx28zhmuHZx6y3hQMCLmuYOT+e7F/eFsYXVEjuJjxjr33uA
O/ii4EkTls1gzvonOtoBoGElzQAogrZI3HXCwFYvU2whLKr9cwv5bpRkUfPCMQ4n
-----END X509 CRL-----

> openssl crl -inform PEM -in 1revoked.crl -text -noout
Certificate Revocation List (CRL):
        Version 2 (0x1)
        Signature Algorithm: sha1WithRSAEncryption
        Issuer: /CN=Puppet CA: localhost
        Last Update: Oct  7 19:48:40 2013 GMT
        Next Update: Oct  6 19:48:41 2018 GMT
        CRL extensions:
            X509v3 CRL Number:
                1
Revoked Certificates:
    Serial Number: 05
        Revocation Date: Oct  7 19:48:41 2013 GMT
        CRL entry extensions:
            X509v3 CRL Reason Code:
                Key Compromise
    Signature Algorithm: sha1WithRSAEncryption
        ba:e1:e3:d5:8d:76:6a:c9:38:f0:91:9e:d0:f5:9f:10:8e:6e:
        6a:99:82:5f:19:c1:3b:fb:4c:ef:55:92:60:86:2a:cb:e8:f3:
        34:76:69:32:0e:1f:d5:54:2a:a5:ab:13:4b:2a:ba:1b:45:25:
        79:7c:77:12:f8:3d:1d:51:88:b6:e6:84:ee:dd:a7:e3:47:76:
        ef:1e:8d:34:29:a0:e4:e9:87:af:71:6d:01:53:de:81:dc:21:
        d9:f6:70:11:ab:2c:94:1c:66:05:ec:8a:cc:13:d0:a2:7c:9e:
        ec:3a:78:33:bd:df:25:c3:ae:0b:92:51:da:2e:f7:d3:3d:f7:
        04:f0:da:79:f5:91:44:0a:5b:d6:f4:bd:42:3b:b7:60:03:17:
        95:3c:fc:31:12:fb:52:2b:bc:1a:b6:20:41:e6:83:8f:9e:91:
        94:42:c5:e2:4c:ba:a7:75:47:5d:e0:ca:67:09:a2:c4:8f:6d:
        18:08:8c:29:62:eb:30:f7:68:ae:0d:ab:93:8c:32:95:4b:57:
        f5:55:3f:0c:90:6f:81:b0:5b:85:a3:e6:2c:8d:02:9f:1d:fc:
        40:2a:b5:9d:b5:64:75:22:9e:fb:97:99:1b:54:58:72:70:7e:
        2e:34:0f:94:f6:19:05:f1:b9:48:c1:e2:99:e1:f1:c1:6a:ed:
        ff:3d:89:4b:ea:a0:2c:05:a3:b9:d1:21:a7:2b:af:07:8d:14:
        c6:03:1b:15:49:54:c7:f3:e0:f9:0f:eb:a7:24:20:f4:39:52:
        e7:b2:f7:67:60:e6:9d:b0:e1:bd:9c:a7:c3:6c:b7:13:1d:81:
        c7:37:28:01:78:f3:72:2d:28:0f:2e:20:3b:94:d5:d6:f3:c3:
        5b:f6:93:9a:94:8e:82:26:b9:e1:f0:2a:89:5b:2e:63:f2:62:
        6b:c5:a7:b8:5b:9d:5f:96:a4:56:ef:1a:3c:88:7d:6d:c1:31:
        a9:e4:0c:4b:f8:8a:0d:0b:30:2c:3a:9f:61:8a:bf:58:52:58:
        ce:8c:ae:4f:09:6b:5c:98:38:52:ec:8c:8d:11:a1:50:99:b1:
        fd:62:36:24:53:db:c8:5a:95:d5:d5:4c:fc:8d:b5:cb:7d:98:
        60:2f:e9:ac:f9:5b:f9:f2:8b:12:0f:ae:b1:ee:6d:3c:76:f3:
        38:66:b8:76:71:eb:2d:e1:40:c0:8b:9a:e6:0e:4f:e7:bb:17:
        f7:85:b1:85:d5:12:3b:89:8f:18:eb:df:7b:80:3b:f8:a2:e0:
        49:13:96:cd:60:ce:fa:27:3a:da:01:a0:61:25:cd:00:28:82:
        b6:48:dc:75:c2:c0:56:2f:53:6c:21:2c:aa:fd:73:0b:f9:6e:
        94:64:51:f3:c2:31:0e:27

No node name given

GET /puppet-ca/v1/certificate_revocation_list?environment=env

HTTP/1.1 400 Bad Request
Content-Type: text/plain

No request key specified in /puppet-ca/v1/certificate_revocation_list

Schema Copy Chapter

A certificate_revocation_list response body is not structured data according to any
standard scheme such as json/pson/yaml, so no schema is applicable.

File: api/docs/http_certificate_status.md Copy Chapter

Certificate Status

The certificate status endpoint allows a client to read or alter the
status of a certificate or pending certificate request. It is only
useful on the CA.

Under Puppet Server's CA service, the environment parameter is ignored and can
be omitted. Under a Rack or WEBrick Puppet master, environment is required and
must be a valid environment, but it has no effect on the response.

Find Copy Chapter

GET /puppet-ca/v1/certificate_status/:certname?environment=:environment
Accept: application/json, text/pson

Retrieve information about the specified certificate. Similar to puppet cert --list :certname.

Search Copy Chapter

GET /puppet-ca/v1/certificate_statuses/:any_key?environment=:environment
Accept: application/json, text/pson

Retrieve information about all known certificates. Similar to puppet cert --list --all. A key is required but is ignored.

Save Copy Chapter

PUT /puppet-ca/v1/certificate_status/:certname?environment=:environment
Content-Type: text/pson

Change the status of the specified certificate. The desired state
is sent in the body of the PUT request as a one-item PSON hash; the two
allowed complete hashes are {"desired_state":"signed"} (for signing a
certificate signing request; similar to puppet cert --sign) and
{"desired_state":"revoked"} (for revoking a certificate; similar to
puppet cert --revoke).

Note that revoking a certificate will not clean up other info about the
host - see the DELETE request for more information.

Delete Copy Chapter

DELETE /puppet-ca/v1/certificate_status/:hostname?environment=:environment
Accept: application/json, text/pson

Cause the certificate authority to discard all SSL information regarding
a host (including any certificates, certificate requests, and keys).
This does not revoke the certificate if one is present; if you wish to
emulate the behavior of puppet cert --clean, you must PUT a
desired_state of revoked before deleting the host’s SSL information.

If the deletion was successful, it returns a string listing the deleted
classes like

"Deleted for myhost: Puppet::SSL::Certificate, Puppet::SSL::Key"

Otherwise it returns

"Nothing was deleted"

Supported HTTP Methods Copy Section

This endpoint is disabled in the default configuration. It is
recommended to be careful with this endpoint, as it can allow control
over the certificates used by the puppet master.

GET, PUT, DELETE

Supported Response Formats Copy Section

application/json, text/pson, pson

This endpoint can produce yaml as well, but the returned data is
incomplete.

Examples Copy Section

Certificate information

GET /puppet-ca/v1/certificate_status/mycertname?environment=env

HTTP/1.1 200 OK
Content-Type: text/pson

{
  "name":"mycertname",
  "state":"signed",
  "fingerprint":"A6:44:08:A6:38:62:88:5B:32:97:20:49:8A:4A:4A:AD:65:C3:3E:A2:4C:30:72:73:02:C5:F3:D4:0E:B7:FC:2F",
  "fingerprints":{
    "default":"A6:44:08:A6:38:62:88:5B:32:97:20:49:8A:4A:4A:AD:65:C3:3E:A2:4C:30:72:73:02:C5:F3:D4:0E:B7:FC:2F",
    "SHA1":"77:E6:5A:7E:DD:83:78:DC:F8:51:E3:8B:12:71:F4:57:F1:C2:34:AE",
    "SHA256":"A6:44:08:A6:38:62:88:5B:32:97:20:49:8A:4A:4A:AD:65:C3:3E:A2:4C:30:72:73:02:C5:F3:D4:0E:B7:FC:2F",
    "SHA512":"CA:A0:8C:B9:FE:9D:C2:72:18:57:08:E9:4B:11:B7:BC:4E:F7:52:C8:9C:76:03:45:B4:B6:C5:D2:DC:E8:79:43:D7:71:1F:5C:97:FA:B2:F3:ED:AE:19:BD:A9:3B:DB:9F:A5:B4:8D:57:3F:40:34:29:50:AA:AA:0A:93:D8:D7:54"
  },
  "dns_alt_names":["DNS:puppet","DNS:mycertname"]
}

Revoking a certificate

PUT /puppet-ca/v1/certificate_status/mycertname?environment=production HTTP/1.1
Content-Type: text/pson
Content-Length: 27

{"desired_state":"revoked"}

This has no meaningful return value.

Deleting the certificate information

DELETE /puppet-ca/v1/certificate_status/mycertname?environment=production HTTP/1.1

Gets the response:

"Deleted for mycertname: Puppet::SSL::Certificate, Puppet::SSL::Key"

Schema Copy Chapter

Find and search operations return objects which
conform to the host schema.

File: api/docs/http_environments.md Copy Chapter

Environments

The environments endpoint allows for enumeration of the environments known to the master. Each environment contains information
about itself like its modulepath, manifest directory, environment timeout, and the config version.
This endpoint is by default accessible to any client with a valid certificate, though this may be changed in Puppet Server's auth.conf.

Get Copy Chapter

Get the list of known environments.

GET /puppet/v3/environments

Supported Response Formats Copy Section

application/json

Parameters Copy Section

None

Example Request & Response Copy Section

GET /puppet/v3/environments

HTTP 200 OK
Content-Type: application/json

{
  "search_paths": ["/etc/puppetlabs/code/environments"]
  "environments": {
    "production": {
      "settings": {
        "modulepath": ["/etc/puppetlabs/code/environments/production/modules", "/etc/puppetlabs/code/environments/development/modules"],
        "manifest": ["/etc/puppetlabs/code/environments/production/manifests"]
        "environment_timeout": 180,
        "config_version": "/version/of/config"
      }
    }
  }
}

The environment_timeout attribute could also be the string "unlimited".

Schema Copy Chapter

An environments response body conforms to
the environments schema.

File: api/docs/http_facts.md Copy Chapter

Facts

The facts endpoint allows setting the facts for the specified node name.

Save Copy Chapter

Store facts for a node. The request body should contain JSON-formatted facts.

PUT /puppet/v3/facts/:nodename?environment=:environment

Supported HTTP Methods Copy Section

PUT

Supported Format(s) Copy Section

application/json

Parameters Copy Section

None

Example Copy Section

• Note: list of facts was shortened for readability.

• Note: JSON was formatted for readability.

  PUT /puppet/v3/facts/elmo.mydomain.com?environment=env
  Content-Type: application/json

  {
  "name": "elmo.mydomain.com",
  "values": {
  "architecture": "x86_64",
  "kernel": "Darwin",
  "domain": "local",
  "macaddress": "70:11:24:8c:33:a9",
  "osfamily": "Darwin",
  "operatingsystem": "Darwin",
  "facterversion": "1.7.2",
  "fqdn": "elmo.mydomain.com",
  },
  "timestamp": "2013-09-09 15:49:27 -0700",
  "expiration": "2013-09-09 16:19:27 -0700"
  
  }

  HTTP/1.1 200 OK
  Content-Type: application/json

Schema Copy Chapter

The representation of facts contained in a PUT body, should adhere to
the facts schema.