puppet-catalog(8)

1PUPPET-CATALOG(8)                Puppet manual               PUPPET-CATALOG(8)
2
3
4

NAME

6       puppet-catalog - Compile, save, view, and convert catalogs.
7

SYNOPSIS

9       puppet catalog action [--terminus _TERMINUS]
10

DESCRIPTION

12       This  subcommand deals with catalogs, which are compiled per-node arti‐
13       facts generated from a set of Puppet manifests. By default,  it  inter‐
14       acts  with the compiling subsystem and compiles a catalog using the de‐
15       fault manifest and certname, but you can change the source of the cata‐
16       log  with the --terminus option. You can also choose to print any cata‐
17       log in ´dot´  format  (for  easy  graph  viewing  with  OmniGraffle  or
18       Graphviz) with ´--render-as dot´.
19

OPTIONS

21       Note  that any setting that´s valid in the configuration file is also a
22       valid long argument, although it may or may  not  be  relevant  to  the
23       present action. For example, server and run_mode are valid settings, so
24       you can specify --server <servername>, or --run_mode  <runmode>  as  an
25       argument.
26
27       See    the    configuration    file   documentation   at   https://pup‐
28       pet.com/docs/puppet/latest/configuration.html for the full list of  ac‐
29       ceptable  parameters. A commented list of all configuration options can
30       also be generated by running puppet with --genconfig.
31
32       --render-as FORMAT
33              The format in which to render output. The  most  common  formats
34              are  json, s (string), yaml, and console, but other options such
35              as dot are sometimes available.
36
37       --verbose
38              Whether to log verbosely.
39
40       --debug
41              Whether to log debug information.
42
43       --extra HASH
44              A terminus can take additional arguments to  refine  the  opera‐
45              tion,  which  are  passed  as an arbitrary hash to the back-end.
46              Anything passed as the extra value is just send  direct  to  the
47              back-end.
48
49       --terminus _TERMINUS
50              Indirector  faces  expose indirected subsystems of Puppet. These
51              subsystems are each able to retrieve and alter a  specific  type
52              of  data  (with  the familiar actions of find, search, save, and
53              destroy) from an arbitrary number of pluggable backends. In Pup‐
54              pet parlance, these backends are called terminuses.
55
56              Almost  all  indirected subsystems have a rest terminus that in‐
57              teracts with the puppet master´s data. Most of them  have  addi‐
58              tional  terminuses  for  various local data models, which are in
59              turn used by the indirected subsystem on the puppet master when‐
60              ever it receives a remote request.
61
62              The  terminus  for an action is often determined by context, but
63              occasionally needs to be set explicitly. See the "Notes" section
64              of this face´s manpage for more details.
65

ACTIONS

67       apply - Find and apply a catalog.
68              SYNOPSIS
69
70              puppet catalog apply [--terminus _TERMINUS]
71
72              DESCRIPTION
73
74              Finds and applies a catalog. This action takes no arguments, but
75              the source of the catalog can be managed with the --terminus op‐
76              tion.
77
78              RETURNS
79
80              Nothing. When used from the Ruby API, returns a Puppet::Transac‐
81              tion::Report object.
82
83       compile - Compile a catalog.
84              SYNOPSIS
85
86              puppet catalog compile [--terminus _TERMINUS]
87
88              DESCRIPTION
89
90              Compiles a catalog locally for a node, requiring access to  mod‐
91              ules, node classifier, etc.
92
93              RETURNS
94
95              A serialized catalog.
96
97       download - Download this node´s catalog from the puppet master server.
98              SYNOPSIS
99
100              puppet catalog download [--terminus _TERMINUS]
101
102              DESCRIPTION
103
104              Retrieves  a  catalog from the puppet master and saves it to the
105              local yaml cache. This action always contacts the puppet  master
106              and will ignore alternate termini.
107
108              The  saved  catalog can be used in any subsequent catalog action
109              by specifying ´--terminus yaml´ for that action.
110
111              RETURNS
112
113              Nothing.
114
115              NOTES
116
117              When used from the Ruby API, this action has a  side  effect  of
118              leaving Puppet::Resource::Catalog.indirection.terminus_class set
119              to yaml. The terminus must be explicitly re-set  for  subsequent
120              catalog actions.
121
122       find - Retrieve the catalog for the node from which the command is run.
123              SYNOPSIS
124
125              puppet catalog find [--terminus _TERMINUS] certname
126
127              DESCRIPTION
128
129              Retrieve the catalog for the node from which the command is run.
130
131              RETURNS
132
133              A  serialized  catalog.  When  used from the Ruby API, returns a
134              Puppet::Resource::Catalog object.
135
136       info - Print the default terminus class for this face.
137              SYNOPSIS
138
139              puppet catalog info [--terminus _TERMINUS]
140
141              DESCRIPTION
142
143              Prints the default terminus class for this subcommand. Note that
144              different  run modes may have different default termini; when in
145              doubt, specify the run mode with the ´--run_mode´ option.
146
147       save - API only: create or overwrite an object.
148              SYNOPSIS
149
150              puppet catalog save [--terminus _TERMINUS] key
151
152              DESCRIPTION
153
154              API only: create or overwrite an object. As the Faces  framework
155              does  not  currently accept data from STDIN, save actions cannot
156              currently be invoked from the command line.
157
158       select - Retrieve a catalog and filter it  for  resources  of  a  given
159       type.
160              SYNOPSIS
161
162              puppet catalog select [--terminus _TERMINUS] host resource_type
163
164              DESCRIPTION
165
166              Retrieves a catalog for the specified host, then searches it for
167              all resources of the requested type.
168
169              RETURNS
170
171              A list of resource references ("Type[title]").  When  used  from
172              the  API,  returns  an array of Puppet::Resource objects excised
173              from a catalog.
174
175              NOTES
176
177              By default, this action will retrieve a  catalog  from  Puppet´s
178              compiler  subsystem;  you  must  call the action with --terminus
179              rest if you wish to retrieve a catalog from the puppet master.
180
181              FORMATTING ISSUES: This action cannot  currently  render  useful
182              yaml; instead, it returns an entire catalog. Use json instead.
183

EXAMPLES

185       apply
186
187       Apply the locally cached catalog:
188
189       $ puppet catalog apply --terminus yaml
190
191       Retrieve a catalog from the master and apply it, in one step:
192
193       $ puppet catalog apply --terminus rest
194
195       API example:
196
197
198
199           # ...
200           Puppet::Face[:catalog, ´0.0.1´].download
201           # (Termini are singletons; catalog.download has a side effect of
202           # setting the catalog terminus to yaml)
203           report  = Puppet::Face[:catalog, ´0.0.1´].apply
204           # ...
205
206
207
208       compile
209
210       Compile catalog for node ´mynode´:
211
212       $ puppet catalog compile mynode --codedir ...
213
214       download
215
216       Retrieve and store a catalog:
217
218       $ puppet catalog download
219
220       API example:
221
222
223
224           Puppet::Face[:plugin, ´0.0.1´].download
225           Puppet::Face[:facts, ´0.0.1´].upload
226           Puppet::Face[:catalog, ´0.0.1´].download
227           # ...
228
229
230
231       select
232
233       Ask the puppet master for a list of managed file resources for a node:
234
235       $ puppet catalog select --terminus rest somenode.magpie.lan file
236

NOTES

238       This  subcommand  is  an  indirector  face, which exposes find, search,
239       save, and destroy actions for an indirected subsystem of Puppet.  Valid
240       termini for this face include:
241
242       •   compiler
243
244       •   json
245
246       •   msgpack
247
248       •   rest
249
250       •   store_configs
251
252       •   yaml
253
254
255

COPYRIGHT AND LICENSE

257       Copyright 2011 by Puppet Inc. Apache 2 license; see COPYING
258
259
260
261Puppet, Inc.                     October 2023                PUPPET-CATALOG(8)