$OpenBSD: README-main,v 1.1.1.1 2016/06/01 12:11:13 jasper Exp $

+-----------------------------------------------------------------------
| Running ${FULLPKGNAME} on OpenBSD
+-----------------------------------------------------------------------

Web frontend
------------
PuppetDB comes with a web frontend which reports various metric at:

    http://<hostname>:8080

Setting up SSL
--------------
In order for the PuppetDB to communicate with the Puppet Master you will need
to setup SSL.

As the Puppet Master need not to run on the same host as PuppetDB we will
assume your configuration is stored in ${SYSCONFDIR}/puppetlabs/puppet/ .

Now manually copy over the following .pem files from your Puppet Master into
${SYSCONFDIR}/puppetlabs/puppetdb/ssl/ (relative to ${SYSCONFDIR}/puppetlabs/puppet/):

    ssl/certs/ca.pem
    ssl/private_keys/<puppet master certname>.pem
    ssl/certs/<puppet master certname>.pem

In order to finalize the setup now run these commands, though if the Puppet
Master runs on the same host as PuppetDB, the first command can be skipped:

    # ${LOCALBASE}/share/puppetdb/cli/apps/puppetdb-ssl-setup
    # puppetdb ssl-setup -f

Setup database
--------------

PuppetDB requires PostgreSQL and no longer supports the builtin KahaDB for
evaluation purposes. To setup a new database for the `puppetdb` user:

	$ doas -u _postgresql createuser -U postgres puppetdb -P
	$ doas -u _postgresql psql -U postgres
        postgres=# create database puppetdb with owner puppetdb;

PostgreSQL indexes
------------------
When using the PostgreSQL database, it is strongly recommended to
create the pg_trgm indexes for the PuppetDB database. This extension
can be installed with:

    # pkg_add postgresql-contrib

Then run the following command as the database super-user on the PuppetDB
database:

    puppetdb=# CREATE EXTENSION pg_trgm;

And restart puppetdb:

    # rcctl restart puppetdb

Configuring the Puppet Master
-----------------------------
Several steps are needed on the Puppet Master to make use of PuppetDB for
storing facts, reports as well as exported resources and stored
configurations.

First create ${SYSCONFDIR}/puppetlabs/puppet/routes.yaml so Puppet can store facts to PuppetDB:

    ---
      master:
        facts:
          terminus: puppetdb
          cache: yaml

Next create ${SYSCONFDIR}/puppetlabs/puppet/puppetdb.conf to teach Puppet how to reach PuppetDB:

    [main]
      server_urls = https://puppetdb.example.com:8081

`server_urls` can contain multiple values, separated by a `,` and HTTPS is required.

Finally instruct Puppet to use PuppetDB for stored configs and reports; in the
'[master]' section of ${SYSCONFDIR}/puppetlabs/puppet/puppet.conf:

    reports      = store,puppetdb
    storeconfigs = true
    storeconfigs_backend = puppetdb

PuppetDB terminus
-----------------
If the Puppet Master is running OpenBSD, you will need to install the PuppetDB
terminus plugin:

    # pkg_add puppetdb-terminus

Upgrade from PuppetDB 2
-----------------------
When upgrading from PuppetDB 2 please take the following into account:
- configuration files moved from ${SYSCONFDIR}/puppetdb/ to ${SYSCONFDIR}/puppetlabs/puppetdb/
  the Puppet 4 configuration files also moved to ${SYSCONFDIR}/puppetlabs/ .
- When migrating your data, please refer to the following page for more information:
  https://docs.puppet.com/puppetdb/3.2/migrate.html#exporting-data-from-an-existing-puppetdb-database
