Forge Home


Tasks that bootstrap/install Puppet Enterprise agents on Linux and Windows


18,449 latest version

4.8 quality score

We run a couple of automated
scans to help you access a
module's quality. Each module is
given a score based on how well
the author has formatted their
code and documentation and
modules are also checked for
malware using VirusTotal.

Please note, the information below
is for guidance only and neither of
these methods should be considered
an endorsement by Puppet.

Version information

  • 2.1.0 (latest)
  • 2.0.0
  • 1.0.0
  • 0.5.0
  • 0.4.1
  • 0.4.0
  • 0.3.0
  • 0.2.0
  • 0.1.1
released Feb 4th 2020
This version is compatible with:
  • Puppet Enterprise 2019.8.x, 2019.7.x, 2019.5.x, 2019.4.x, 2019.3.x, 2019.2.x, 2019.1.x, 2019.0.x, 2018.1.x
  • Puppet >= 5.5.10 < 7.0.0
  • , , , , ,
  • bootstrap

Start using this module

  • r10k or Code Manager
  • Bolt
  • Manual installation
  • Direct download

Add this module to your Puppetfile:

mod 'puppetlabs-bootstrap', '2.1.0'
Learn more about managing modules with a Puppetfile

Add this module to your Bolt project:

bolt module add puppetlabs-bootstrap
Learn more about using this module with an existing project

Manually install this module globally with Puppet module tool:

puppet module install puppetlabs-bootstrap --version 2.1.0

Direct download is not typically how you would use a Puppet module to manage your infrastructure, but you may want to download the module in order to inspect the code.



puppetlabs/bootstrap — version 2.1.0 Feb 4th 2020


Table of Contents

  1. Description
  2. Requirements
  3. Usage - Configuration options and additional functionality
  4. Reference - An under-the-hood peek at what the task is doing and how
  5. Limitations - OS compatibility, etc.
  6. Development - Guide for contributing to the module
  7. Getting help - Some Helpful commands


This module provides the bootstrap task. This allows you to install Puppet agents on un-puppeted hosts via the ssh or winrm transports.


This module requires both the bolt gem on the machine from which you are running bolt commands (the controller node), and a Puppet Enterprise 2017.3 or later master hosting agent repositories.

Linux machines receiving task requests must have bash for now. Windows machines must have PowerShell. (See Limitations for more info.)


To run the bootstrap task, use the bolt command, specifying the PE master from which the Puppet agent package should be installed and to which the agent should submit its certificate for signing.

Example: Basic usage

On the command line:

  • For Linux, run bolt task run bootstrap::linux master=<master's fqdn> --nodes x,y,z --modulepath /path/to/modules
  • For Windows, run bolt task run bootstrap::windows master=<master's fqdn> --nodes x,y,z --modulepath /path/to/modules For all advanced examples below, simply replace bootstrap::linux by bootstrap::windows to perform the action on Windows.

Example: Verify the master's CA on initial connection

Optionally to validate the connection during the bootstrap process, specify the puppet master's CA cert by adding the cacert_content option: bolt task run bootstrap::linux master=<master's fqdn> cacert_content="$(cat /etc/puppetlabs/puppet/ssl/certs/ca.pem)" --nodes x,y,z --modulepath /path/to/modules

Example: Specify a custom certname

Optionally to install the Puppet agent with a certname other than the fqdn of the target node, specify the custom certname: bolt task run bootstrap::linux master=<master's fqdn> certname=<custom certname> --nodes x,y,z --modulepath /path/to/modules

Example: Specify the environment

Optionally to install the puppet-agent with a specific environment other than the default environment production, specify the custom environment: bolt task run bootstrap::linux master=<master's fqdn> environment=<custom environment> --nodes x,y,z --modulepath /path/to/modules

Example: Specify custom dns alt names

Optionally to install the Puppet agent with custom dns alt names, specify the custom dns alt names: bolt task run bootstrap::linux master=<master's fqdn> dns_alt_names=<comma-separated list of alt names for the node> --nodes x,y,z --modulepath /path/to/modules (see Compile master installation documentation for more info).

You can also run tasks in the PE console. See PE task documentation for complete information.

Example: Specify a custom_attribute

Optionally to install the Puppet agent and adding a setting to puppet.conf and including it in the custom_attributes section of csr_attributes.yaml: bolt task run bootstrap master=<master's fqdn> custom_attribute=key=value --nodes x,y,z --modulepath /path/to/modules

Example: Specify a extension_request

Optionally to install the Puppet agent and adding a setting to puppet.conf and including it in the extension_requests section of csr_attributes.yaml: bolt task run bootstrap master=<master's fqdn> extension_request=key=value --nodes x,y,z --modulepath /path/to/modules


For detailed reference information, see the


The bootstrap task currently installs the agent via the Puppet Enterprise package management tools, and FOSS repository support will be added later. See the Puppet Enterprise documentation for more information.

For an extensive list of supported operating systems, see metadata.json

The bootstrap task is tested to work with Windows Management Framework >= v3.0+ and .NET >= v4.6 on the supported Windows operating systems.


Acceptance tests for this module leverage puppet_litmus. To run the acceptance tests follow the instructions here. You can also find a tutorial and walkthrough of using Litmus and the PDK on YouTube.

If you run into an issue with this module, or if you would like to request a feature, please file a ticket. Every Monday the Puppet IA Content Team has office hours in the Puppet Community Slack, alternating between an EMEA friendly time (1300 UTC) and an Americas friendly time (0900 Pacific, 1700 UTC).

If you have problems getting this module up and running, please contact Support.

If you submit a change to this module, be sure to regenerate the reference documentation as follows:

puppet strings generate --format markdown --out

Getting Help

To display help for the bootstrap task, run puppet task show bootstrap::linux or puppet task show bootstrap::windows

To show help for the task CLI, run puppet task run --help or bolt task run --help