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       --terminus _TERMINUS
44              Indirector faces expose indirected subsystems of  Puppet.  These
45              subsystems  are  each able to retrieve and alter a specific type
46              of data (with the familiar actions of find,  search,  save,  and
47              destroy) from an arbitrary number of pluggable backends. In Pup‐
48              pet parlance, these backends are called terminuses.
49
50              Almost all indirected subsystems have a rest terminus  that  in‐
51              teracts  with  the puppet master´s data. Most of them have addi‐
52              tional terminuses for various local data models,  which  are  in
53              turn used by the indirected subsystem on the puppet master when‐
54              ever it receives a remote request.
55
56              The terminus for an action is often determined by  context,  but
57              occasionally needs to be set explicitly. See the "Notes" section
58              of this face´s manpage for more details.
59

ACTIONS

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

EXAMPLES

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

NOTES

232       This subcommand is an indirector  face,  which  exposes  find,  search,
233       save,  and destroy actions for an indirected subsystem of Puppet. Valid
234       termini for this face include:
235
236       •   compiler
237
238       •   json
239
240       •   msgpack
241
242       •   rest
243
244       •   store_configs
245
246       •   yaml
247
248
249

251       Copyright 2011 by Puppet Inc. Apache 2 license; see COPYING
252
253
254
255Puppet, Inc.                     October 2023                PUPPET-CATALOG(8)
Impressum