Go to main content

man pages section 8: System Administration Commands

Exit Print View

Updated: Thursday, June 13, 2019
 
 

puppet-module (8)

Name

puppet-module - pet Forge.

Synopsis

puppet module action [--environment production ] [--modulepath ]

Description

PUPPET-MODULE(8)                 Puppet manual                PUPPET-MODULE(8)



NAME
       puppet-module  - Creates, installs and searches for modules on the Pup-
       pet Forge.

SYNOPSIS
       puppet module action [--environment production ] [--modulepath ]

DESCRIPTION
       This subcommand can find, install, and manage modules from  the  Puppet
       Forge, a repository of user-contributed Puppet code. It can also gener-
       ate empty modules, and prepare locally developed modules for release on
       the Forge.

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.

       --environment production
              The environment in which Puppet is running. For clients, such as
              puppet agent, this determines the environment itself, which Pup-
              pet uses to find modules and much more.  For  servers,  such  as
              puppet  master,  this provides the default environment for nodes
              that Puppet knows nothing about.

              When defining an environment in the [agent] section, this refers
              to  the environment that the agent requests from the master. The
              environment doesn't  have  to  exist  on  the  local  filesystem
              because the agent fetches it from the master. This definition is
              used when running puppet agent.

              When defined in the [user] section, the  environment  refers  to
              the path that Puppet uses to search for code and modules related
              to its execution. This requires the environment to exist locally
              on the filesystem where puppet is being executed. Puppet subcom-
              mands, including puppet module and puppet apply, use this  defi-
              nition.

              Given  that the context and effects vary depending on the config
              section               https://puppet.com/docs/puppet/latest/con-
              fig_file_main.html#config-sections in which the environment set-
              ting is defined, do not set it globally.

       --modulepath
              The search path for modules, as a list of directories  separated
              by  the system path separator character. (The POSIX path separa-
              tor is ':', and the Windows path separator is ';'.)

              Setting a global value for  modulepath  in  puppet.conf  is  not
              allowed  (but it can be overridden from the commandline). Please
              use directory environments instead. If you need to use something
              other  than the default modulepath of <ACTIVE ENVIRONMENT'S MOD-
              ULES DIR>:$basemodulepath, you can set  modulepath  in  environ-
              ment.conf.   For  more  info,  see  https://docs.puppet.com/pup-
              pet/latest/reference/environments.html

ACTIONS
       build - Build a module release package.
              SYNOPSIS

              puppet module build [path]

              DESCRIPTION

              Prepares a local module for  release  on  the  Puppet  Forge  by
              building a ready-to-upload archive file. Note: Module build uses
              MD5 checksums, which are prohibited on FIPS enabled systems.

              This action uses the metadata.json file in the module  directory
              to  set  metadata  used  by  the Forge. See https://docs.puppet-
              labs.com/puppet/latest/reference/modules_publishing.html     for
              more about writing metadata.json files.

              After  being built, the release archive file can be found in the
              module's pkg directory.

              RETURNS

              Pathname object representing the path to the release archive.

       changes - Show modified files of an installed module.
              SYNOPSIS

              puppet module changes path

              DESCRIPTION

              Shows any files in a module that have been modified since it was
              installed.  This  action  compares  the files on disk to the md5
              checksums included in the module's checksums.json or, if that is
              missing, in metadata.json.

              RETURNS

              Array of strings representing paths of modified files.

       generate - Generate boilerplate for a new module.
              SYNOPSIS

              puppet module generate [--skip-interview] name

              DESCRIPTION

              Generates boilerplate for a new module by creating the directory
              structure and files recommended for the Puppet community's  best
              practices.

              A module may need additional directories beyond this boilerplate
              if it provides plugins, files, or templates.

              OPTIONS --skip-interview - Do not attempt to perform a  metadata
              interview.  Primarily  useful  for automatic execution of puppet
              module generate.

              RETURNS

              Array of Pathname objects representing paths of generated files.

       install - Install a module from the Puppet Forge or a release archive.
              SYNOPSIS

              puppet module install [--force | -f] [--target-dir DIR | -i DIR]
              [--ignore-dependencies]     [--version    VER    |    -v    VER]
              [--strict-semver] name

              DESCRIPTION

              Installs a module from the Puppet Forge or from  a  release  ar-
              chive  file.  Note: Module install uses MD5 checksums, which are
              prohibited on FIPS enabled systems.

              The specified module will be installed into the directory speci-
              fied  with  the --target-dir option, which defaults to the first
              directory in the modulepath.

              OPTIONS --force | -f - Force overwrite of  existing  module,  if
              any. Implies --ignore-dependencies.

              --ignore-dependencies  - Do not attempt to install dependencies.
              Implied by --force.

              --strict-semver  -  Whether  version   ranges   should   exclude
              pre-release versions

              --target-dir DIR | -i DIR - The directory into which modules are
              installed; defaults to the first directory in the modulepath.

              Specifying this option will change the  installation  directory,
              and will use the existing modulepath when checking for dependen-
              cies. If you wish to check a different set  of  directories  for
              dependencies,  you  must  also  use  the --environment or --mod-
              ulepath options.

              --version VER | -v VER - Module version to install;  can  be  an
              exact  version  or a requirement string, eg '>= 1.0.3'. Defaults
              to latest version.

              RETURNS

              Pathname object representing the path to the installed module.

       list - List installed modules
              SYNOPSIS

              puppet module list [--tree] [--strict-semver]

              DESCRIPTION

              Lists the installed puppet  modules.  By  default,  this  action
              scans  the  modulepath  from puppet.conf's [main] block; use the
              --modulepath option to change which directories are scanned.

              The output of this action includes information from the module's
              metadata,  including  version numbers and unmet module dependen-
              cies.

              OPTIONS --strict-semver - Whether version ranges should  exclude
              pre-release versions

              --tree - Whether to show dependencies as a tree view

              RETURNS

              hash of paths to module objects

       search - Search the Puppet Forge for a module.
              SYNOPSIS

              puppet module search search_term

              DESCRIPTION

              Searches  a repository for modules whose names, descriptions, or
              keywords match the provided search term.

              RETURNS

              Array of module metadata hashes

       uninstall - Uninstall a puppet module.
              SYNOPSIS

              puppet module uninstall [--force | -f] [--ignore-changes  |  -c]
              [--version=] [--strict-semver] name

              DESCRIPTION

              Uninstalls  a  puppet  module from the modulepath (or a specific
              target directory). Note: Module uninstall  uses  MD5  checksums,
              which are prohibited on FIPS enabled systems.

              OPTIONS  --force | -f - Force the uninstall of an installed mod-
              ule even if there are local changes or the possibility of  caus-
              ing broken dependencies.

              --ignore-changes  |  -c  - Uninstall an installed module even if
              there are local changes to it. (Implied by --force.)

              --strict-semver  -  Whether  version   ranges   should   exclude
              pre-release versions

              --version=  - The version of the module to uninstall. When using
              this option, a module matching the  specified  version  must  be
              installed or else an error is raised.

              RETURNS

              Hash  of  module  objects  representing  uninstalled modules and
              related errors.

       upgrade - Upgrade a puppet module.
              SYNOPSIS

              puppet module upgrade  [--force  |  -f]  [--ignore-dependencies]
              [--ignore-changes | -c] [--version=] [--strict-semver] name

              DESCRIPTION

              Upgrades  a  puppet module. Note: Module upgrade uses MD5 check-
              sums, which are prohibited on FIPS enabled systems.

              OPTIONS --force | -f - Force the upgrade of an installed  module
              even  if  there  are local changes or the possibility of causing
              broken dependencies. Implies --ignore-dependencies.

              --ignore-changes | -c - Upgrade  an  installed  module  even  if
              there are local changes to it. (Implied by --force.)

              --ignore-dependencies  - Do not attempt to install dependencies.
              Implied by --force.

              --strict-semver  -  Whether  version   ranges   should   exclude
              pre-release versions

              --version= - The version of the module to upgrade to.

              RETURNS

              Hash

EXAMPLES
       build

       Build a module release:

       $ puppet module build puppetlabs-apache notice: Building /Users/kelsey-
       hightower/puppetlabs-apache for release  Module  built:  /Users/kelsey-
       hightower/puppetlabs-apache/pkg/puppetlabs-apache-0.0.1.tar.gz

       Build the module in the current working directory:

       $  cd  /Users/kelseyhightower/puppetlabs-apache  $  puppet module build
       notice: Building /Users/kelseyhightower/puppetlabs-apache  for  release
       Module    built:   /Users/kelseyhightower/puppetlabs-apache/pkg/puppet-
       labs-apache-0.0.1.tar.gz

       changes

       Show modified files of an installed module:

       $ puppet module changes /etc/puppetlabs/code/modules/vcsrepo/  warning:
       1 files modified lib/puppet/provider/vcsrepo.rb

       generate

       Generate a new module in the current directory:

       $  puppet  module  generate  puppetlabs-ssh  We  need to create a meta-
       data.json file for this module. Please answer the following  questions;
       if the question is not applicable to this module, feel free to leave it
       blank.

       Puppet uses Semantic Versioning (semver.org) to version  modules.  What
       version is this module? [0.1.0] -->

       Who wrote this module? [puppetlabs] -->

       What license does this module code fall under? [Apache-2.0] -->

       How would you describe this module in a single sentence? -->

       Where is this module's source code repository? -->

       Where can others go to learn more about this module? -->

       Where can others go to file issues about this module? -->

       { "name": "puppetlabs-ssh", "version": "0.1.0", "author": "puppetlabs",
       "summary": null, "license": "Apache-2.0", "source": "", "project_page":
       null,   "issues_url":   null,  "dependencies":  [  {  "name":  "puppet-
       labs-stdlib", "version_requirement": ">= 1.0.0" } ]

}
       About to generate this metadata; continue? [n/Y] -->

       Notice: Generating  module  at  /Users/username/Projects/puppet/puppet-
       labs-ssh... Notice: Populating ERB templates... Finished; module gener-
       ated in puppetlabs-ssh.  puppetlabs-ssh/manifests  puppetlabs-ssh/mani-
       fests/init.pp   puppetlabs-ssh/metadata.json   puppetlabs-ssh/README.md
       puppetlabs-ssh/spec     puppetlabs-ssh/spec/spec_helper.rb      puppet-
       labs-ssh/tests puppetlabs-ssh/tests/init.pp

       install

       Install a module:

       $  puppet  module  install puppetlabs-vcsrepo Preparing to install into
       /etc/puppetlabs/code/modules ... Downloading from https://forgeapi.pup-
       pet.com   ...   Installing   --   do  not  interrupt  ...  /etc/puppet-
       labs/code/modules  puppetlabs-vcsrepo (v0.0.4)

       Install a module to a specific environment:

       $ puppet module install  puppetlabs-vcsrepo  --environment  development
       Preparing  to  install  into /etc/puppetlabs/code/environments/develop-
       ment/modules  ...  Downloading  from  https://forgeapi.puppet.com   ...
       Installing   --  do  not  interrupt  ...  /etc/puppetlabs/code/environ-
       ments/development/modules  puppetlabs-vcsrepo (v0.0.4)

       Install a specific module version:

       $ puppet  module  install  puppetlabs-vcsrepo  -v  0.0.4  Preparing  to
       install    into    /etc/puppetlabs/modules    ...    Downloading   from
       https://forgeapi.puppet.com ... Installing  --  do  not  interrupt  ...
       /etc/puppetlabs/code/modules  puppetlabs-vcsrepo (v0.0.4)

       Install a module into a specific directory:

       $  puppet  module  install puppetlabs-vcsrepo --target-dir=/usr/puppet-
       labs/puppet/modules  Preparing  to  install  into  /usr/puppetlabs/pup-
       pet/modules   ...   Downloading  from  https://forgeapi.puppet.com  ...
       Installing -- do not interrupt ... /usr/puppetlabs/puppet/modules  pup-
       petlabs-vcsrepo (v0.0.4)

       Install  a  module into a specific directory and check for dependencies
       in other directories:

       $ puppet module  install  puppetlabs-vcsrepo  --target-dir=/usr/puppet-
       labs/puppet/modules --modulepath /etc/puppetlabs/code/modules Preparing
       to install into  /usr/puppetlabs/puppet/modules  ...  Downloading  from
       https://forgeapi.puppet.com  ...  Installing  --  do  not interrupt ...
       /usr/puppetlabs/puppet/modules  puppetlabs-vcsrepo (v0.0.4)

       Install a module from a release archive:

       $ puppet module install  puppetlabs-vcsrepo-0.0.4.tar.gz  Preparing  to
       install   into   /etc/puppetlabs/code/modules   ...   Downloading  from
       https://forgeapi.puppet.com ... Installing  --  do  not  interrupt  ...
       /etc/puppetlabs/code/modules  puppetlabs-vcsrepo (v0.0.4)

       Install a module from a release archive and ignore dependencies:

       $ puppet module install puppetlabs-vcsrepo-0.0.4.tar.gz --ignore-depen-
       dencies Preparing  to  install  into  /etc/puppetlabs/code/modules  ...
       Installing  --  do not interrupt ... /etc/puppetlabs/code/modules  pup-
       petlabs-vcsrepo (v0.0.4)

       list

       List installed modules:

       $  puppet   module   list   /etc/puppetlabs/code/modules    bodepd-cre-
       ate_resources  (v0.0.1)   puppetlabs-bacula  (v0.0.2)  puppetlabs-mysql
       (v0.0.1)   puppetlabs-sqlite   (v0.0.1)    puppetlabs-stdlib   (v2.2.1)
       /usr/puppetlabs/puppet/modules (no modules installed)

       List installed modules in a tree view:

       $  puppet  module  list  --tree  /etc/puppetlabs/code/modules   puppet-
       labs-bacula  (v0.0.2)   puppetlabs-stdlib  (v2.2.1)    puppetlabs-mysql
       (v0.0.1)   |    bodepd-create_resources   (v0.0.1)    puppetlabs-sqlite
       (v0.0.1) /usr/puppetlabs/puppet/modules (no modules installed)

       List installed modules from a specified environment:

       $ puppet module list --environment production /etc/puppetlabs/code/mod-
       ules    bodepd-create_resources  (v0.0.1)   puppetlabs-bacula  (v0.0.2)
       puppetlabs-mysql   (v0.0.1)    puppetlabs-sqlite   (v0.0.1)     puppet-
       labs-stdlib   (v2.2.1)   /usr/puppetlabs/puppet/modules   (no   modules
       installed)

       List installed modules from a specified modulepath:

       $  puppet  module  list   --modulepath   /usr/puppetlabs/puppet/modules
       /usr/puppetlabs/puppet/modules (no modules installed)

       search

       Search the Puppet Forge for a module:

       $ puppet module search puppetlabs NAME DESCRIPTION AUTHOR KEYWORDS bac-
       ula This is a generic Apache module @puppetlabs backups

       uninstall

       Uninstall a module:

       $  puppet  module   uninstall   puppetlabs-ssh   Removed   /etc/puppet-
       labs/code/modules/ssh (v1.0.0)

       Uninstall a module from a specific directory:

       $  puppet  module  uninstall  puppetlabs-ssh  --modulepath /usr/puppet-
       labs/puppet/modules Removed /usr/puppetlabs/puppet/modules/ssh (v1.0.0)

       Uninstall a module from a specific environment:

       $ puppet  module  uninstall  puppetlabs-ssh  --environment  development
       Removed       /etc/puppetlabs/code/environments/development/modules/ssh
       (v1.0.0)

       Uninstall a specific version of a module:

       $  puppet  module  uninstall  puppetlabs-ssh  --version  2.0.0  Removed
       /etc/puppetlabs/code/modules/ssh (v2.0.0)

       upgrade

       upgrade an installed module to the latest version

       $  puppet  module upgrade puppetlabs-apache /etc/puppetlabs/puppet/mod-
       ules  puppetlabs-apache (v1.0.0 -> v2.4.0)

       upgrade an installed module to a specific version

       $ puppet module upgrade puppetlabs-apache --version 2.1.0  /etc/puppet-
       labs/puppet/modules  puppetlabs-apache (v1.0.0 -> v2.1.0)

       upgrade an installed module for a specific environment

       $  puppet module upgrade puppetlabs-apache --environment test /etc/pup-
       petlabs/code/environments/test/modules   puppetlabs-apache  (v1.0.0  ->
       v2.4.0)

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



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


       +---------------+--------------------------+
       |ATTRIBUTE TYPE |     ATTRIBUTE VALUE      |
       +---------------+--------------------------+
       |Availability   | system/management/puppet |
       +---------------+--------------------------+
       |Stability      | Volatile                 |
       +---------------+--------------------------+
NOTES
       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-MODULE(8)