ppdb.1

.TH ppdb 1 "2015-12-05" "version 0.2.1" "Hieracles command manual"

.SH NAME
ppdb \- Command line tool to query puppetdb
.SH SYNOPSIS
.B ppdb 
.I command
.B [
.I options
.B ]

.SH DESCRIPTION
.PP
This tool is part of the Hieracles tools suite.
.PP
PuppetDB stores information gathered by Puppet when nodes run 
the puppet client. It exposes a very neat REST interface, but 
its query system can be a little complicated.
.PP
The purpose of 
.B ppdb
is to overlay the calls to the REST API and propose a more
user-friendly way to query the Puppet Database (puppetdb).
.PP
Note that this tool is designed to work fine with the version 3 
of the PuppetDB API.
.PP
Ref http://docs.puppetlabs.com/puppetdb/2.3/api/
.PP
.B ppdb
takes a command, plus extra parameters depending the command.

.TP
.PD 0
.B node info \fR<fqdn>
will display the equivalent of 
.I "GET /v3/nodes/<NODE>"
and takes the node 
.B certname
as an argument. 
.RS 10
Optionaly, you can add a filter to limit what fields are displayed.
.TP
eg. ppdb node info <fqdn>
.RS
will display all the fields from the API response
.RE
eg. ppdb node info <fqdn> time
.RS
will only display the fields containing 
.I time
in their label.
.RE
.RE

.TP
.PD 0
.B node facts \fR<fqdn>
will display the equivalent of 
.I "GET /v3/nodes/<NODE>/facts"
and takes the node 
.B certname
as an argument. 
.RS 10
As the result can be verbose, you can add a filter to limit what 
fields are displayed.
.TP
eg. ppdb node facts <fqdn>
.RS
will display all the fields from the API response
.RE
eg. ppdb node facts <fqdn> memory
.RS
will only display the fields containing 
.I memory
in their label.
.RE
.RE

.TP
.PD 0
.B node resources \fR<fqdn>
will display the equivalent of 
.I "GET /v3/nodes/<NODE>/resources"
and takes the node 
.B certname
as an argument. You can use 
.I res
instead of 
.I resources
for shorter.
.RS 10
As the result can be verbose, you can add a filter to limit what 
resources are displayed.
.TP
eg. ppdb node res <fqdn>
.RS
will display all the fields from the API response
.RE
eg. ppdb node res <fqdn> nagios
.RS
will only display the fields containing 
.I nagios
in their label.
.RE
.RE

.RE

.TP
.PD 0
.B facts <name> <value>
will list all fqdn (aka. certnames) of the nodes having the <name> 
fact set to <value>.
.RS
eq. ppdb facts puppet_environment dev
.RE

.TP
.PD 0
.B same <name> <fqdn>
will list all the fqdn having the same value for the fact <name> as
<fqdn> has.
.RS
eq. ppdb same farm node32.example.com
.RE

.TP
.PD 0
.B resources <queries>
.TP
.PD
.B res <queries>
will list the resources matching a given set of queries. 
Queries are a combination of statements, with a label, an operator
and a value. You can use 
.I or
to separate one or several statements. If there is no
.I or
indicated, the statements follow an
.I and 
logic. All statements that don't contain an operator or match the 
.I or
keyword are purely ignored (which makes possible to use the 
.I and
keyword for mental stability purpose).

.RS
Operators can be >, <, =, ~ and can be prefixed by a ! to negate them.
.RS
eq. ppdb res type=Nagios_ghost and tag~api
.RE
.RS
eq. ppdb res tag~api title!~dev
.RE
.RS
eq. ppdb res tag~api or certname~api or title~api
.RE
.RE

.TP
.PD 0
.B factnames
will list all the factnames puppetdb knows about.
This may be a long list.

.SH OPTIONS

.TP
.PD 0
.B \-v
.TP
.PD
.B \-\-version
outputs version.

.TP
.PD 0
.B \-f \fRformat
.TP
.PD
.B \-\-format \fRformat
outputs in the selected format. For now only the json format
is available as an alternative to the default console format.


.SH FILES
.I ~/.config/hieracles/config.yaml
.RS
ppdb uses the same configuration file as hieracles, and relies on
its information to find the url of the PuppetDB

.SH EXAMPLES
A typical config file would contain, at minimum:
.PP
.RS
---
.RE
.RS
puppetdb:
.RS
  usessl: false
.RE
.RS
  host: localhost
.RE
.RS
  port: 8080
.RE
.RE

.SH SEE ALSO
hiera(1), puppet(8), hc(1)

.SH BUGS
Please report any bug to https://github.com/Gandi/hieracles/issues

.SH AUTHORS
Copyright (c) 2015 gandi.net https://gandi.net
.LP
Hieracles is written by mose@gandi.net
.LP
https://github.com/Gandi/hieracles