1--- 2title: "Connecting Puppet Servers to PuppetDB" 3layout: default 4canonical: "/puppetdb/latest/connect_puppet_server.html" 5--- 6 7# Connecting Puppet Servers to PuppetDB 8 9[puppetdb_download]: http://downloads.puppetlabs.com/puppetdb 10[puppetdb_conf]: ./puppetdb_connection.markdown 11[routes_yaml]: https://puppet.com/docs/puppet/latest/config_file_routes.html 12[exported]: https://puppet.com/docs/puppet/latest/lang_exported.html 13[install_via_module]: ./install_via_module.markdown 14[report_processors]: https://puppet.com/docs/puppet/latest/reporting_about.html 15[event]: ./api/query/v4/events.markdown 16[report]: ./api/query/v4/reports.markdown 17[store_report]: ./api/command/v1/commands.markdown#store-report-version-7 18[report_format]: ./api/wire_format/report_format_v5.markdown 19[puppetdb_server_urls]: ./puppetdb_connection.markdown#serverurls 20 21> Note: To use PuppetDB, your site's Puppet Server(s) must be running 22> Puppet version 5.0.0 or later. 23 24After PuppetDB is installed and running, configure your Puppet Server to use it. When properly connected to PuppetDB, the Puppet Server does the following: 25 26* Send every node's catalog, facts, and reports to PuppetDB 27* Query PuppetDB when compiling node catalogs that collect [exported resources][exported] 28 29> Note: if you've [installed PuppetDB using the PuppetDB module][install_via_module], then the `puppetdb::master::config` class is taking care of all of this for you. 30 31 **Working on your Puppet Server(s),** follow all of the instructions below: 32 33## Step 1: Install plug-ins 34 35Currently, Puppet Servers need additional Ruby plug-ins 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. 36 37### On platforms with packages 38 39[Enable the Puppet Collection repo](https://puppet.com/docs/puppet/latest/puppet_collections.html) and then install the `puppetdb-termini` package: 40 41 $ sudo puppet resource package puppetdb-termini ensure=latest 42 43### On platforms without packages 44 45If your Puppet Server isn't running Puppet from a supported package, you will need to install the plugins manually: 46 47* [Download the PuppetDB source code][puppetdb_download], unzip it, and navigate into the resulting directory in your terminal. 48 49* Run `sudo cp -R puppet/lib/puppet/ /opt/puppetlabs/puppet/lib/ruby/vendor_ruby/puppet` 50 51## Step 2: Edit configuration files 52 53### Locate Puppet's config directory 54 55Find your Puppet Server's config directory by running `sudo puppet config print confdir`. It will usually be at either `/etc/puppet/` or `/etc/puppetlabs/puppet/`. 56 57You will edit (or create) three files in this directory: 58 59### 1. Edit puppetdb.conf 60 61The [puppetdb.conf][puppetdb_conf] file will probably not yet exist. Create it, and add the PuppetDB server's URL that includes the hostname and port: 62 63 [main] 64 server_urls = https://puppetdb.example.com:8081 65 66PuppetDB's port for secure traffic defaults to 8081 with the context root of '/'. If you have not changed the defaults, the above configuration (with the correct hostname) is sufficient. For more information on configuring `server_urls`, including support for multiple PuppetDB backends, see [configuring the PuppetDB server_urls][puppetdb_server_urls]. 67 68### 2. Edit puppet.conf 69 70To enable saving facts and catalogs in PuppetDB, edit the `[master]` block of puppet.conf to reflect the following settings: 71 72 [master] 73 storeconfigs = true 74 storeconfigs_backend = puppetdb 75 76> Note: The `thin_storeconfigs` and `async_storeconfigs` settings should be absent or set to `false`. If you previously used the Puppet queue daemon (puppetqd), you should now disable it. 77 78#### Enabling report storage 79 80PuppetDB includes support for storing Puppet reports. This feature can be 81enabled by simply adding the `puppetdb` report processor in your `puppet.conf` 82file. If you don't already have a `reports` setting in your `puppet.conf` 83file, you'll probably want to add a line like this: 84 85 reports = store,puppetdb 86 87This will retain Puppet's default behavior of storing the reports to disk as YAML, 88while also sending the reports to PuppetDB. 89 90You can configure how long PuppetDB stores these reports, and you can do some 91very basic querying. For more information, see: 92 93* [The `event` query endpoint][event] 94* [The `report` query endpoint][report] 95* [The `store report` command][store_report] 96* [The report wire format][report_format] 97 98More information about Puppet report processors in general can be found 99[here][report_processors]. 100 101### 3. Edit routes.yaml 102 103The [routes.yaml][routes_yaml] file will probably not yet exist. Find the path to this Puppet configuration file by running `puppet config print route_file`. 104 105Create the file, if necessary, and add the following: 106 107 --- 108 master: 109 facts: 110 terminus: puppetdb 111 cache: yaml 112 113### Ensure proper ownership of the config files 114 115The files created above need to be owned by the `puppet` user. Ensure that 116this ownership is applied by running the following command: 117 118 $ sudo chown -R puppet:puppet `sudo puppet config print confdir` 119 120## Step 3: Set security policy 121 122PuppetDB listens on TCP port 8081 (HTTPS). Ensure that this port is open between 123the Puppet Server and PuppetDB services. If the services run on the same server, additional configuration might not be needed. If the services are on separate 124servers, ensure that the server and network firewalls allow for traffic flow. 125 126PuppetDB works without modification with SELinux in enforcing mode. 127 128## Step 4: Restart Puppet Server 129 130Use your system's service tools to restart the Puppet Server service. For open source Puppet users, the command to do this will vary, depending on the frontend web server being used. 131 132> Your Puppet Server is now using PuppetDB to store and retrieve catalogs, facts, and exported resources. You can test your setup by triggering a Puppet agent run on an arbitrary node, then logging into your PuppetDB server and viewing the `/var/log/puppetlabs/puppetdb/puppetdb.log` file, which will include calls to the "replace facts", "replace catalog", and "store report" commands: 133> 134> 2012-05-17 13:08:41,664 INFO [command-proc-67] [puppetdb.command] [85beb105-5f4a-4257-a5ed-cdf0d07aa1a5] [replace facts] screech.example.com 135> 2012-05-17 13:08:45,993 INFO [command-proc-67] [puppetdb.command] [3a910863-6b33-4717-95d2-39edf92c8610] [replace catalog] screech.example.com 136