Using the PE docs

Review these tips to get the most out of the PE docs.

Using example commands

These guidelines can help you understand and customize example commands included in the Puppet Enterprise (PE) docs.

puppet commands generate cURL arguments

Some examples in the PE docs use puppet commands to populate some cURL arguments and take the guesswork out of providing those values. For example:
url="http://$(puppet config print server):4433"
curl "$url"

puppet commands can return different values depending on various conditions. To use cURL examples successfully, run the entire example (including setting the environment variables and the curl command) as root, Administrator, or with equivalent elevated privileges.

To run commands on a machine without elevated privileges, replace the inline puppet commands with hard-coded values. If you’re unsure about the correct values, run the puppet commands to get reasonable default values.

Authentication tokens in cURL commands

If a curl command requires authentication, the example might contain this line: 
auth_header="X-Authentication: $(puppet-access show)"
If you have an actual authentication token available, you can use that in the command instead, such as:
auth_header="X-Authentication: <TOKEN>"

Modifications for Windows

While the commands in the PE docs are primarily *nix-based, Windows-specific commands are provided in topics focusing exclusively on Windows systems.

There are various options for running curl commands directly in Windows, such as:
  • Installing the curl executable for Windows.
  • Using built-in curl functionality included with Git for Windows.
  • Using the GNU Bash shell.
If you're using PowerShell, you can use these equivalent commands to modify *nix curl commands for use in Windows:
Native curl PowerShell equivalent
curl Invoke-WebRequest
-k or --insecure [System.Net.ServicePointManager]::ServerCertificateValidationCallback = $true
-H -Headers
-X -Method
-d -Body
\ (line-continuation character) `
You can learn more about Invoke-WebRequest and the arguments it accepts in the Microsoft PowerShelldocumentation.

Commands with elevated privileges

Some commands in PE require elevated privileges. Depending on the operating system, youc an use either sudo, runas, or a root or admin user.

Elevated privileges allow you to access and do more than you might be able to with your personal account privileges. There are three primary methods for using elevated privileges:
root (or administrator)
In *nix systems, the root user has virtually unlimited access to read, write, or change files and system configurations; install,uninstall, and upgrade software; or perform any operation as any user. The equivalent in Windows is the administrator.
sudo
The sudo command, which means super user do, allows a user to execute a command from a personal user account with temporarily elevated privileges. With sudo, you can do most of the things the root user can do without actually logging in as the root user.
Run as administrator or runas
Using the runas command or running a program as an administrator (for example, by right-clicking the program and selecting Run as administrator) is the Windows equivalent of sudo – It allows you to temporarily perform administrator functions without actually logging in as the administrator.
You can use sudo to run almost all commands in Puppet with the exception of puppet infrastructure commands, which require you to be logged in as the root user (or administrator). You can run puppet infrastructure help <ACTION> to get information about puppet infrastructure commands.
Restriction: You must log in as the root user (or administrator) to run puppet infrastructure commands.

In Windows systems, use runas or open the command prompt as an administrator (recommended for PowerShell commands) instead of using sudo.

Documentation for other PE versions

Documentation for each PE version is initially published on our documentation website (where you are now). We actively maintain documentation for our leading-edge PE release stream (also known as STS), the current LTS stream, and, when applicable, the ongoing support stream (which is the previous LTS until it reaches EOL).

Documentation for end-of-life (EOL) and superseded major versions (formatted as <YEAR>.y, such as 2023.0, 2023.1, and so on) may continue to be available on our documentation website while no longer being updated, and, eventually, moved to our PE docs archive on GitHub.

For LTS releases, we do not separately publish documentation for each incremental version (formatted as <YEAR>.y.z, such as 2021.7.0, 2021.7.1, and so on). To find PDFs of prior LTS incremental versions, go to our PE docs archive on GitHub.

When we start a new LTS stream, we continue to host (but do not update) the prior major versions for that stream for some time. For example, if the LTS is 2021.7.z, then we retain 2021.0 through 2021.6 for a limited amount of time. For the prior LTS, we continue to host the latest increment of that stream during the overlap support period and up to one year after.

To find documentation for any version earlier than the current LTS stream's earliest major version (such as 2021.0) or, when applicable, the most recent overlap support incremental version, go to our PE docs archive on GitHub.

Archived documentation is commonly retained as PDF. You may find some older versions retained in markdown format.

This table describes where you can find documentation for various PE versions and release streams:
PE Version URL
2021.7.z (LTS) https://puppet.com/docs/pe/2021.7/pe_user_guide.html
2019.8.z (overlap support) You're currently viewing the documentation for the most-recent incremental release of our overlap support stream.

For earlier incremental releases, go to the PE docs archive on GitHub.
2019.7 https://puppet.com/docs/pe/2019.7/pe_user_guide.html
Earlier versions PE docs archive on GitHub