<commit_before>---
title: "Connecting standalone Puppet nodes to PuppetDB"
layout: default
canonical: "/puppetdb/latest/connect_puppet_apply.markdown"
---

# Connecting standalone Puppet nodes to PuppetDB

[exported]: https://puppet.com/docs/puppet/latest/lang_exported.html
[package]: https://puppet.com/docs/puppet/latest/type.html#package
[file]: https://puppet.com/docs/puppet/latest/type.html#file
[yumrepo]: https://puppet.com/docs/puppet/latest/type.html#yumrepo
[apt]: http://forge.puppetlabs.com/puppetlabs/apt
[puppetdb_download]: http://downloads.puppetlabs.com/puppetdb
[puppetdb_conf]: https://puppet.com/docs/puppet/latest/config_file_puppetdb.html
[routes_yaml]: https://puppet.com/docs/puppet/latest/config_file_routes.html
[exported]: https://puppet.com/docs/puppet/latest/lang_exported.html
[jetty]: ./configure.markdown#jetty-http-settings
[ssl_script]: ./maintain_and_tune.markdown#redo-ssl-setup-after-changing-certificates
[settings_namespace]: https://puppet.com/docs/puppet/latest/lang_facts_and_builtin_vars.html#puppet-master-variables
[package_repos]: https://puppet.com/docs/puppet/latest/puppet_collections.html

> **Note:** To use PuppetDB, the nodes at your site must be running Puppet version 3.8.1 or later.

PuppetDB can be used with standalone Puppet deployments where each node runs `puppet apply`. When connected to PuppetDB, `puppet apply` does the following:

* Send the node's catalog to PuppetDB
* Query PuppetDB when compiling catalogs that collect [exported resources][exported]
* Store facts in PuppetDB
* Send reports to PuppetDB (optional)

You must take the following steps to configure your standalone nodes to connect to PuppetDB. Note that because you must change Puppet's configuration on every managed node, **we strongly recommend that you do so with Puppet itself.**

## Step 1: Configure SSL

PuppetDB requires client authentication (CA) for its SSL connections, and the PuppetDB-termini require SSL to talk to PuppetDB. You must configure Puppet and PuppetDB to work around this double-bind by using one of the following options:

### Option A (Recommended): Issue certificates to all Puppet nodes

This option is recommended. The Puppet team optimizes for this option when they're developing, and it is better tested.

When talking to PuppetDB, `puppet apply` can use the certificates issued by a Puppet Server's certificate authority. You can issue certificates to every node by setting up a Puppet Server server with dummy manifests, running `puppet agent --test` one time on every node, signing every certificate request on the Puppet Server, and running `puppet agent --test` again on every node.

Do the same on your PuppetDB node, then [re-run the SSL setup script][ssl_script] (which usually runs automatically during installation). PuppetDB will now trust connections from your Puppet nodes.

You will have to sign a certificate for every new node you add to your site.

### Option B: Set up an SSL proxy for PuppetDB

Before you head down this path, please consider if signing certificates with Puppet Server will work for you.
This option requires more work on your part to set up, and does not allow you to provide
SSL to PuppetDB without a signed certificate, but it will allow you to provide SSL connections to PuppetDB using an existing CA.
If you have an existing CA you would like to use, you can [set up Puppet Server as an intermediate CA](https://puppet.com/docs/puppetserver/latest/intermediate_ca.html#set-up-puppet-as-an-intermediate-ca-with-an-external-root) and then follow the instructions in Option A.

1. Edit [the `[jetty]` section of the PuppetDB config files][jetty] to remove all SSL-related settings.
2. Install a general-purpose web server (like Apache or NGINX) on the PuppetDB server.
3. Configure the web server to listen on port 8081 with SSL enabled and proxy all traffic to `localhost:8080` (or whatever unencrypted hostname and port were set in [jetty.ini][jetty]).
   The cacert used will need to be signed.

If you use this option, you'll need to add these settings in addition
to the general ones specified below. The cacert supplied to `localcacert`
should be the one that signs the SSL proxy cert for PuppetDB.

Add this to your `puppetdb.conf`
```
[main]
verify_client_certificate = false
```

Add this to your `puppet.conf`
```
[main]
localcacert = /etc/path/to/cacert/ca.crt
certificate_revocation = false
```


## Step 2: Install terminus plugins on every Puppet node

Currently, Puppet needs extra Ruby plugins in order to use PuppetDB. Unlike custom facts or functions, these cannot be loaded from a module and must be installed in Puppet's main source directory.

* First, ensure that the appropriate [Puppet Collection repository][package_repos]
  repository is enabled. You can use a [package][] resource to do this or the
  `apt::source` (from the [puppetlabs-apt][apt] module) and [`yumrepo`][yumrepo] types.
* Next, use Puppet to ensure that the `puppetdb-termini` package is installed:

~~~ ruby
    package {'puppetdb-termini':
      ensure => installed,
    }
~~~

### On platforms without packages

If your Puppet Server isn't running Puppet from a supported package, you will need to install the plugins using [file][] resources.

* [Download the PuppetDB source code][puppetdb_download]; unzip it, locate the `puppet/lib/puppet` directory, and put it in the `files` directory of the Puppet module you are using to enable PuppetDB integration.
* Identify the install location of Puppet on your nodes.
* Create a [file][] resource in your manifest(s) for each of the plugin files, to move them into place on each node.<commit_msg>(PDB-5365) Update puppet repository link in node connection docs<commit_after>---
title: "Connecting standalone Puppet nodes to PuppetDB"
layout: default
canonical: "/puppetdb/latest/connect_puppet_apply.markdown"
---

# Connecting standalone Puppet nodes to PuppetDB

[exported]: https://puppet.com/docs/puppet/latest/lang_exported.html
[package]: https://puppet.com/docs/puppet/latest/type.html#package
[file]: https://puppet.com/docs/puppet/latest/type.html#file
[yumrepo]: https://puppet.com/docs/puppet/latest/type.html#yumrepo
[apt]: http://forge.puppetlabs.com/puppetlabs/apt
[puppetdb_download]: http://downloads.puppetlabs.com/puppetdb
[puppetdb_conf]: https://puppet.com/docs/puppet/latest/config_file_puppetdb.html
[routes_yaml]: https://puppet.com/docs/puppet/latest/config_file_routes.html
[exported]: https://puppet.com/docs/puppet/latest/lang_exported.html
[jetty]: ./configure.markdown#jetty-http-settings
[ssl_script]: ./maintain_and_tune.markdown#redo-ssl-setup-after-changing-certificates
[settings_namespace]: https://puppet.com/docs/puppet/latest/lang_facts_and_builtin_vars.html#puppet-master-variables
[package_repos]: https://puppet.com/docs/puppet/6/install_puppet.html#enable_the_puppet_platform_repository

> **Note:** To use PuppetDB, the nodes at your site must be running Puppet version 3.8.1 or later.

PuppetDB can be used with standalone Puppet deployments where each node runs `puppet apply`. When connected to PuppetDB, `puppet apply` does the following:

* Send the node's catalog to PuppetDB
* Query PuppetDB when compiling catalogs that collect [exported resources][exported]
* Store facts in PuppetDB
* Send reports to PuppetDB (optional)

You must take the following steps to configure your standalone nodes to connect to PuppetDB. Note that because you must change Puppet's configuration on every managed node, **we strongly recommend that you do so with Puppet itself.**

## Step 1: Configure SSL

PuppetDB requires client authentication (CA) for its SSL connections, and the PuppetDB-termini require SSL to talk to PuppetDB. You must configure Puppet and PuppetDB to work around this double-bind by using one of the following options:

### Option A (Recommended): Issue certificates to all Puppet nodes

This option is recommended. The Puppet team optimizes for this option when they're developing, and it is better tested.

When talking to PuppetDB, `puppet apply` can use the certificates issued by a Puppet Server's certificate authority. You can issue certificates to every node by setting up a Puppet Server server with dummy manifests, running `puppet agent --test` one time on every node, signing every certificate request on the Puppet Server, and running `puppet agent --test` again on every node.

Do the same on your PuppetDB node, then [re-run the SSL setup script][ssl_script] (which usually runs automatically during installation). PuppetDB will now trust connections from your Puppet nodes.

You will have to sign a certificate for every new node you add to your site.

### Option B: Set up an SSL proxy for PuppetDB

Before you head down this path, please consider if signing certificates with Puppet Server will work for you.
This option requires more work on your part to set up, and does not allow you to provide
SSL to PuppetDB without a signed certificate, but it will allow you to provide SSL connections to PuppetDB using an existing CA.
If you have an existing CA you would like to use, you can [set up Puppet Server as an intermediate CA](https://puppet.com/docs/puppetserver/latest/intermediate_ca.html#set-up-puppet-as-an-intermediate-ca-with-an-external-root) and then follow the instructions in Option A.

1. Edit [the `[jetty]` section of the PuppetDB config files][jetty] to remove all SSL-related settings.
2. Install a general-purpose web server (like Apache or NGINX) on the PuppetDB server.
3. Configure the web server to listen on port 8081 with SSL enabled and proxy all traffic to `localhost:8080` (or whatever unencrypted hostname and port were set in [jetty.ini][jetty]).
   The cacert used will need to be signed.

If you use this option, you'll need to add these settings in addition
to the general ones specified below. The cacert supplied to `localcacert`
should be the one that signs the SSL proxy cert for PuppetDB.

Add this to your `puppetdb.conf`
```
[main]
verify_client_certificate = false
```

Add this to your `puppet.conf`
```
[main]
localcacert = /etc/path/to/cacert/ca.crt
certificate_revocation = false
```


## Step 2: Install terminus plugins on every Puppet node

Currently, Puppet needs extra Ruby plugins in order to use PuppetDB. Unlike custom facts or functions, these cannot be loaded from a module and must be installed in Puppet's main source directory.

* First, ensure that the appropriate [Puppet platform repository][package_repos]
  repository is enabled. You can use a [package][] resource to do this or the
  `apt::source` (from the [puppetlabs-apt][apt] module) and [`yumrepo`][yumrepo] types.
* Next, use Puppet to ensure that the `puppetdb-termini` package is installed:

~~~ ruby
    package {'puppetdb-termini':
      ensure => installed,
    }
~~~

### On platforms without packages

If your Puppet Server isn't running Puppet from a supported package, you will need to install the plugins using [file][] resources.

* [Download the PuppetDB source code][puppetdb_download]; unzip it, locate the `puppet/lib/puppet` directory, and put it in the `files` directory of the Puppet module you are using to enable PuppetDB integration.
* Identify the install location of Puppet on your nodes.
* Create a [file][] resource in your manifest(s) for each of the plugin files, to move them into place on each node.
{'fraction_non_alphanumeric': 0.08018287321962371, 'fraction_numerical': 0.0032530332336908737, 'mean_word_length': 4.881592554291624, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 7, 'https://': 20, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 8, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '663556', 'n_tokens_mistral': 3452, 'n_tokens_neox': 3359, 'n_words': 1417}