Go to main content

man pages section 8: System Administration Commands

Exit Print View

Updated: Thursday, June 13, 2019
 
 

puppet-catalog (8)

Name

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

Synopsis

puppet catalog action [--terminus _TERMINUS] [--extra HASH]

Description

PUPPET-CATALOG(8)                Puppet manual               PUPPET-CATALOG(8)



NAME
       puppet-catalog - Compile, save, view, and convert catalogs.

SYNOPSIS
       puppet catalog action [--terminus _TERMINUS] [--extra HASH]

DESCRIPTION
       This  subcommand deals with catalogs, which are compiled per-node arti-
       facts generated from a set of Puppet manifests. By default,  it  inter-
       acts  with  the  compiling  subsystem  and compiles a catalog using the
       default manifest and certname, but you can change  the  source  of  the
       catalog  with  the  --terminus option. You can also choose to print any
       catalog in 'dot' format (for easy graph  viewing  with  OmniGraffle  or
       Graphviz) with '--render-as dot'.

OPTIONS
       Note  that any setting that's valid in the configuration file is also a
       valid long argument, although it may or may  not  be  relevant  to  the
       present action. For example, server and run_mode are valid settings, so
       you can specify --server <servername>, or --run_mode  <runmode>  as  an
       argument.

       See   the  configuration  file  documentation  at  https://docs.puppet-
       labs.com/puppet/latest/reference/configuration.html for the  full  list
       of acceptable parameters. A commented list of all configuration options
       can also be generated by running puppet with --genconfig.

       --render-as FORMAT
              The format in which to render output. The  most  common  formats
              are  json, s (string), yaml, and console, but other options such
              as dot are sometimes available.

       --verbose
              Whether to log verbosely.

       --debug
              Whether to log debug information.

       --extra HASH
              A terminus can take additional arguments to  refine  the  opera-
              tion,  which  are  passed  as an arbitrary hash to the back-end.
              Anything passed as the extra value is just send  direct  to  the
              back-end.

       --terminus _TERMINUS
              Indirector  faces  expose indirected subsystems of Puppet. These
              subsystems are each able to retrieve and alter a  specific  type
              of  data  (with  the familiar actions of find, search, save, and
              destroy) from an arbitrary number of pluggable backends. In Pup-
              pet parlance, these backends are called terminuses.

              Almost  all  indirected  subsystems  have  a  rest terminus that
              interacts with the puppet master's data. Most of them have addi-
              tional  terminuses  for  various local data models, which are in
              turn used by the indirected subsystem on the puppet master when-
              ever it receives a remote request.

              The  terminus  for an action is often determined by context, but
              occasionally needs to be set explicitly. See the "Notes" section
              of this face's manpage for more details.

ACTIONS
       apply - Find and apply a catalog.
              SYNOPSIS

              puppet catalog apply [--terminus _TERMINUS] [--extra HASH]

              DESCRIPTION

              Finds and applies a catalog. This action takes no arguments, but
              the source of the catalog can be  managed  with  the  --terminus
              option.

              RETURNS

              Nothing. When used from the Ruby API, returns a Puppet::Transac-
              tion::Report object.

       download - Download this node's catalog from the puppet master server.
              SYNOPSIS

              puppet catalog download [--terminus _TERMINUS] [--extra HASH]

              DESCRIPTION

              Retrieves a catalog from the puppet master and saves it  to  the
              local  yaml cache. This action always contacts the puppet master
              and will ignore alternate termini.

              The saved catalog can be used in any subsequent  catalog  action
              by specifying '--terminus yaml' for that action.

              RETURNS

              Nothing.

              NOTES

              When  used  from  the Ruby API, this action has a side effect of
              leaving Puppet::Resource::Catalog.indirection.terminus_class set
              to  yaml.  The terminus must be explicitly re-set for subsequent
              catalog actions.

       find - Retrieve the catalog for a node.
              SYNOPSIS

              puppet catalog find [--terminus _TERMINUS] [--extra HASH]  cert-
              name

              DESCRIPTION

              Retrieve the catalog for a node.

              RETURNS

              A  serialized  catalog.  When  used from the Ruby API, returns a
              Puppet::Resource::Catalog object.

       info - Print the default terminus class for this face.
              SYNOPSIS

              puppet catalog info [--terminus _TERMINUS] [--extra HASH]

              DESCRIPTION

              Prints the default terminus class for this subcommand. Note that
              different  run modes may have different default termini; when in
              doubt, specify the run mode with the '--run_mode' option.

       save - API only: create or overwrite an object.
              SYNOPSIS

              puppet catalog save [--terminus _TERMINUS] [--extra HASH] key

              DESCRIPTION

              API only: create or overwrite an object. As the Faces  framework
              does  not  currently accept data from STDIN, save actions cannot
              currently be invoked from the command line.

       select - Retrieve a catalog and filter it  for  resources  of  a  given
       type.
              SYNOPSIS

              puppet catalog select [--terminus _TERMINUS] [--extra HASH] host
              resource_type

              DESCRIPTION

              Retrieves a catalog for the specified host, then searches it for
              all resources of the requested type.

              RETURNS

              A  list  of  resource references ("Type[title]"). When used from
              the API, returns an array of  Puppet::Resource  objects  excised
              from a catalog.

              NOTES

              By  default,  this  action will retrieve a catalog from Puppet's
              compiler subsystem; you must call  the  action  with  --terminus
              rest if you wish to retrieve a catalog from the puppet master.

              FORMATTING  ISSUES:  This  action cannot currently render useful
              yaml; instead, it returns an entire catalog. Use json instead.

EXAMPLES
       apply

       Apply the locally cached catalog:

       $ puppet catalog apply --terminus yaml

       Retrieve a catalog from the master and apply it, in one step:

       $ puppet catalog apply --terminus rest

       API example:



           # ...
           Puppet::Face[:catalog, '0.0.1'].download
           # (Termini are singletons; catalog.download has a side effect of
           # setting the catalog terminus to yaml)
           report  = Puppet::Face[:catalog, '0.0.1'].apply
           # ...



       download

       Retrieve and store a catalog:

       $ puppet catalog download

       API example:



           Puppet::Face[:plugin, '0.0.1'].download
           Puppet::Face[:facts, '0.0.1'].upload
           Puppet::Face[:catalog, '0.0.1'].download
           # ...



       select

       Ask the puppet master for a list of managed file resources for a node:

       $ puppet catalog select --terminus rest somenode.magpie.lan file


ATTRIBUTES
       See attributes(7) for descriptions of the following attributes:


       +---------------+--------------------------+
       |ATTRIBUTE TYPE |     ATTRIBUTE VALUE      |
       +---------------+--------------------------+
       |Availability   | system/management/puppet |
       +---------------+--------------------------+
       |Stability      | Volatile                 |
       +---------------+--------------------------+
NOTES
       This subcommand is an indirector  face,  which  exposes  find,  search,
       save,  and destroy actions for an indirected subsystem of Puppet. Valid
       termini for this face include:

       o   compiler

       o   json

       o   msgpack

       o   rest

       o   store_configs

       o   yaml



COPYRIGHT AND LICENSE
       Copyright 2011 by Puppet Inc. Apache 2 license; see COPYING


       This    software    was    built    from    source     available     at
       https://github.com/oracle/solaris-userland.    The  original  community
       source was  downloaded  from   https://github.com/puppetlabs/puppet/ar-
       chive/5.5.0.tar.gz

       Further information about this software can be found on the open source
       community website at http://puppetlabs.com/.



Puppet, Inc.                      March 2018                 PUPPET-CATALOG(8)