Bolt configuration options

Sections

Global configuration options

Global configuration options can be set in the configuration file.

OptionDescriptionDefault
apply_settingsA map of Puppet settings to use when applying Puppet code
colorWhether to use colored output when printing messages to the console.true
compile-concurrencyThe maximum number of simultaneous manifest block compiles.Number of cores
concurrencyThe number of threads to use when executing on remote targets.100
formatThe format to use when printing results. Options are human and json.human
hiera-configThe path to your Hiera config.Boltdir/hiera.yaml
inventoryfileThe path to a structured data inventory file used to refer to groups of targets on the command line and from plans.Boltdir/inventory.yaml
logThe configuration of the logfile output. Configuration can be set for console and the path to a log file, such as ~/.puppetlabs/bolt/debug.log.
modulepathThe module path for loading tasks and plan code. This is either an array of directories or a string containing a list of directories separated by the OS-specific PATH separator.
plugin_hooksWhich plugins a specific hook should use.
pluginsA map of plugins and their configuration data.
puppetdbA map containing options for configuring the Bolt PuppetDB client.
puppetfileA map containing options for the bolt puppetfile install command.
save-rerunWhether to update .rerun.json in the Bolt project directory. If your target names include passwords, set this value to false to avoid writing passwords to disk.true
transportThe default transport to use when the transport for a target is not specified in the URL or inventory.
trusted-external-commandThe path to an executable on the Bolt controller that can produce external trusted facts. External trusted facts are experimental in both Puppet and Bolt and this API may change or be removed.

Log file configuration options

You can configure how the results of plan runs are captured in a log file. Different log files can be configured by specifying the log file's location using either console or a path to the log file, such as ~/.puppetlabs/bolt/debug.log.

OptionDescriptionDefault
appendAdd output to an existing log file. Available only for logs output to a filepath.true
levelThe type of information in the log. Either debug, info, notice, warn, or error.warn for console, notice for file

Example configuration

Setting log configuration in the configuration file:

log:
  console:
    level: error
  ~/.puppetlabs/bolt/debug.log:
    level: debug

Plugin hooks configuration options

The plugin_hooks section allows you to configure which plugins a specific hook should use for a specific target. This section is a hash where keys are hook names, and values specify and configure the plugin that that hook should use. There are two possible plugins: the install_agent plugin runs the puppet_agent::install task, and the task plugin runs your own custom task.

For now, the only configurable plugin hook is puppet_library.

The default is to use the puppet_agent plugin with the agent service stopped:

plugin_hooks:
  puppet_library:
    plugin: puppet_agent
    stop_service: true

The puppet_agent::install task will error if it's not run as root. To ensure this plugin to succeeds on non-root targets set _run_as: true for the puppet_agent plugin.

plugin_hooks:
  puppet_library:
    plugin: puppet_agent
    _run_as: root

You can use the bootstrap task to connect all targets to a PE master instead:

plugin_hooks:
  puppet_library:
    plugin: task
    _run_as: root
    task: 'bootstrap'
    parameters:
      master: 'puppet.example.com'
      cacert_content: <CERT>

You can also configure plugin_hooks using _plugin references:

plugin_hooks:
  puppet_library:
    plugin: puppet_agent
    version:
      _plugin: prompt
      message: "Which version of Puppet do you want to install?"

Apply options

Apply options are a subset of Puppet configuration settings which are set when Bolt applies Puppet code on remote targets. Users can define values for the following Puppet settings:

OptionDescriptionDefault
show_diffWhether to log and report a contextual diff when files are being replaced. See Puppet documentation for detailsfalse

Puppetfile configuration options

The puppetfile section of the configuration file configures how to retrieve modules when running bolt puppetfile install.

OptionDescription
forgeA subsection that can have its own proxy setting to set an HTTP proxy for Forge operations only, and a baseurl setting to specify a different Forge host.
proxyThe HTTP proxy to use for Git and Forge operations.

Transport configuration options

Transport configuration options can be set in both the configuration file and inventory file.

ssh

OptionDescriptionTypeDefault
connect-timeoutHow long to wait when establishing connections.Integer10
disconnect-timeoutHow long to wait before force-closing a connection.Integer5
hostHost name.String
host-key-checkWhether to perform host key validation when connecting.Boolean
interpretersA map of an extension name to the absolute path of an executable, enabling you to override the shebang defined in a task executable. The extension can optionally be specified with the . character (.py and py both map to a task executable task.py) and the extension is case sensitive. When a target's name is localhost, Ruby tasks run with the Bolt Ruby interpreter by default.Hash
load-configWhether to load system SSH configuration.Booleantrue
passwordLogin password.String
portConnection port.Integer
private-keyEither the path to the private key file to use for authentication, or a hash with the key key-data and the contents of the private key.
proxyjumpA jump host to proxy connections through, and an optional user to connect with.String
run-asA different user to run commands as after login.String
run-as-commandThe command to elevate permissions. Bolt appends the user and command strings to the configured run-as-command before running it on the target. This command must not require an interactive password prompt, and the sudo-password option is ignored when run-as-command is specified. The run-as-command must be specified as an array.Array
script-dirThe subdirectory of the tmpdir to use in place of a randomized subdirectory for uploading and executing temporary files on the target. It's expected that this directory already exists as a subdir of tmpdir, which is either configured or defaults to /tmp.String
sudo-executableThe executable to use when escalating to the configured run-as user. This is useful when you want to escalate using the configured sudo-password, since run-as-command does not use sudo-password or support prompting. The command executed on the target is <sudo-executable> -S -u <user> -p custom_bolt_prompt <command>. This option is experimental.String
sudo-passwordPassword to use when changing users via run-as.String
tmpdirThe directory to upload and execute temporary files on the target.String
ttyRequest a pseudo tty for the session. This option is generally only used in conjunction with the run-as option when the sudoers policy requires a tty.Booleanfalse
userLogin user.String

OpenSSH

In addition to the SSH transport options, some additional SSH options are read from OpenSSH configuration files, including ~/.ssh/config, /etc/ssh_config, and /etc/ssh/ssh_config. Not all OpenSSH configuration values have equivalents in Bolt.

These are the options configurable in OpenSSH files:

OptionDescription
CiphersCiphers allowed in order of preference. Multiple ciphers must be comma-separated.
CompressionWhether to use compression.
CompressionLevelCompression level to use if compression is enabled.
GlobalKnownHostsFilePath to global host key database.
HostKeyAlgorithmsHost key algorithms that the client wants to use in order of preference.
HostKeyAliasUse alias instead of real hostname when looking up or saving the host key in the host key database file.
HostNameHost name to log.
IdentityFileFile in which user's identity key is stored.
PortSSH port.
UserLogin user.
UserKnownHostsFilePath to local user's host key database.

Note: For OpenSSH configuration options with direct equivalents in Bolt, such as user and port, the settings in Bolt config take precedence.

To illustrate, consider this example:

targets:
  - name: host1.example.net
    config:
      transport: ssh
      ssh:
        host-key-check: true
        port: 22
        private-key: ~/.ssh/id_rsa-example
Host *.example.net
  UserKnownHostsFile=~/.ssh/known_hosts
  User root
  Port 444

In this example, the SSH connection is configured to use the user and known hosts file defined in OpenSSH config and the port defined in Bolt's config.

Note: The host-key-check option must be set in Bolt config because the StrictHostKeyChecking OpenSSH configuration value is ignored.

When using the SSH transport, Bolt also interacts with the ssh-agent for SSH key management. The most common interaction is to handle password protected private keys. When a private key is password protected it must be added to the ssh-agent in order to be used to authenticate Bolt SSH connections.

winrm

OptionDescriptionTypeDefault
basic-auth-onlyForce basic authentication. This option is only available when using SSL.Booleanfalse
cacertThe path to the CA certificate.String
connect-timeoutHow long Bolt should wait when establishing connections.Integer10
extensionsList of file extensions that are accepted for scripts or tasks. Scripts with these file extensions rely on the target's file type association to run. For example, if Python is installed on the system, a .py script runs with python.exe. The extensions .ps1, .rb, and .pp are always allowed and run via hard-coded executables.Array
file-protocolWhich file transfer protocol to use. Either winrm or smb. Using smb is recommended for large file transfers.Stringwinrm
hostHost name.String
interpretersA map of an extension name to the absolute path of an executable, enabling you to override the shebang defined in a task executable. The extension can optionally be specified with the . character (.py and py both map to a task executable task.py) and the extension is case sensitive. When a target's name is localhost, Ruby tasks run with the Bolt Ruby interpreter by default.Hash
passwordLogin password. Required unless using Kerberos.String
portConnection port.Integer
realmKerberos realm (Active Directory domain) to authenticate against.String
smb-portWith file-protocol set to smb, this is the port to establish a connection on.Integer
sslWhen true, Bolt uses secure https connections for WinRM.Booleantrue
ssl-verifyWhen true, verifies the targets certificate matches the cacert.Booleantrue
tmpdirThe directory to upload and execute temporary files on the target.String
userLogin user. Required unless using Kerberos.String

pcp

OptionDescriptionTypeDefault
cacertThe path to the CA certificate.String
hostHost name.String
job-poll-intervalSet interval to poll orchestrator for job status.Integer
job-poll-timeoutSet time to wait for orchestrator job status.Integer
service-urlThe URL of the orchestrator API.String
task-environmentThe environment the orchestrator loads task code from.Stringproduction
token-fileThe path to the token file.String

local

OptionDescriptionTypeDefault
interpretersA map of an extension name to the absolute path of an executable, enabling you to override the shebang defined in a task executable. The extension can optionally be specified with the . character (.py and py both map to a task executable task.py) and the extension is case sensitive. When a target's name is localhost, Ruby tasks run with the Bolt Ruby interpreter by default.Hash
run-asA different user to run commands as after login.String
run-as-commandThe command to elevate permissions. Bolt appends the user and command strings to the configured run-as-command before running it on the target. This command must not require an interactive password prompt, and the sudo-password option is ignored when run-as-command is specified. The run-as-command must be specified as an array.Array
sudo-executableThe executable to use when escalating to the configured run-as user. This is useful when you want to escalate using the configured sudo-password, since run-as-command does not use sudo-password or support prompting. The command executed on the target is <sudo-executable> -S -u <user> -p custom_bolt_prompt <command>. This option is experimental.String
sudo-passwordPassword to use when changing users via run-as.String
tmpdirThe directory to copy and execute temporary files.String

docker

OptionDescriptionTypeDefault
hostHost name.String
interpretersA map of an extension name to the absolute path of an executable, enabling you to override the shebang defined in a task executable. The extension can optionally be specified with the . character (.py and py both map to a task executable task.py) and the extension is case sensitive. When a target's name is localhost, Ruby tasks run with the Bolt Ruby interpreter by default.Hash
service-urlURL of the Docker host used for API requests.String
shell-commandA shell command to wrap any Docker exec commands in, such as bash -lc.String
tmpdirThe directory to upload and execute temporary files on the target.String
ttyWhether to enable tty on exec commands.Boolean

remote

OptionDescriptionTypeDefault
run-onThe proxy target that the task executes on.Stringlocalhost
How helpful was this page?
Puppet sites use proprietary and third-party cookies. By using our sites, you agree to our cookie policy.