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 the example commands you'll find in the Puppet Enterprise (PE) docs.
Ports, paths, and other input
puppet commands to populate variables and curl
arguments. This can take the guesswork out of providing those values. In the
following example, the puppet config print server
command supplies the DNS name for a curl
command:url="http://$(puppet config print server):4433"
curl "$url"puppet commands generate cert
paths:--cert $(puppet config print --section main hostcert) \
--key $(puppet config print --section main hostprivkey) \
--cacert $(puppet config print --section main localcacert) \puppet commands can return different values depending
on various conditions. Make sure you run the entire example (including commands
setting environment variables and the curl command)
as the root, administrator, or with equivalent elevated privileges.
To run such commands on a machine without elevated privileges, you must replace the
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
curl command requires token-based
authentication, the example might contain this line:
auth_header="X-Authentication: $(puppet-access show)"auth_header="X-Authentication: <TOKEN>"For instructions on generating, configuring, revoking, and deleting authentication tokens in PE, go to Token-based authentication.
Modifications for Windows
\) as line-continuation characters.
In Windows, the equivalent characters are carets
(^) and, for PowerShell specifically, backticks (`).Additionally, *nix commands use forward slashes (/) as
directory separator characters. You might use either backslashes or forward
slashes as directory separator characters in your Windows commands; however some modules and
commands require you to use one or the other. For modules, check the
module's Forge page for information about Windows modifications or
requirements.
Furthermore, Windows commands might require wrapping strings or arguments in double quotes rather than single quotes.
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.
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 |
\ (as a line-continuation
character) |
` |
Invoke-WebRequest
and the arguments it accepts in the Microsoft
PowerShelldocumentation. You can also
learn about running Puppet language commands
on Windows in the Puppet
documentation.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.
- 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
sudocommand, which means super user do, allows a user to execute a command from a personal user account with temporarily elevated privileges. Withsudo, 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
runascommand or running a program as an administrator (for example, by right-clicking the program and selecting Run as administrator) is the Windows equivalent ofsudo– It allows you to temporarily perform administrator functions without actually logging in as the administrator.
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.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, you must 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.