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

NAME

6       puppet-module  - Creates, installs and searches for modules on the Pup‐
7       pet Forge.
8

SYNOPSIS

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

DESCRIPTION

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

OPTIONS

19       Note  that any setting that´s valid in the configuration file is also a
20       valid long argument, although it may or may  not  be  relevant  to  the
21       present action. For example, server and run_mode are valid settings, so
22       you can specify --server <servername>, or --run_mode  <runmode>  as  an
23       argument.
24
25       See    the    configuration    file   documentation   at   https://pup
26       pet.com/docs/puppet/latest/configuration.html  for  the  full  list  of
27       acceptable  parameters.  A  commented list of all configuration options
28       can also be generated by running puppet with --genconfig.
29
30       --render-as FORMAT
31              The format in which to render output. The  most  common  formats
32              are  json, s (string), yaml, and console, but other options such
33              as dot are sometimes available.
34
35       --verbose
36              Whether to log verbosely.
37
38       --debug
39              Whether to log debug information.
40
41       --environment production
42              The environment in which Puppet is running. For clients, such as
43              puppet agent, this determines the environment itself, which Pup‐
44              pet uses to find modules and much more.  For  servers,  such  as
45              puppet  master,  this provides the default environment for nodes
46              that Puppet knows nothing about.
47
48              When defining an environment in the [agent] section, this refers
49              to  the environment that the agent requests from the master. The
50              environment doesn´t  have  to  exist  on  the  local  filesystem
51              because the agent fetches it from the master. This definition is
52              used when running puppet agent.
53
54              When defined in the [user] section, the  environment  refers  to
55              the path that Puppet uses to search for code and modules related
56              to its execution. This requires the environment to exist locally
57              on the filesystem where puppet is being executed. Puppet subcom‐
58              mands, including puppet module and puppet apply, use this  defi‐
59              nition.
60
61              Given  that the context and effects vary depending on the config
62              section               https://puppet.com/docs/puppet/latest/con
63              fig_file_main.html#config-sections in which the environment set‐
64              ting is defined, do not set it globally.
65
66       --modulepath
67              The search path for modules, as a list of directories  separated
68              by  the system path separator character. (The POSIX path separa‐
69              tor is ´:´, and the Windows path separator is ´;´.)
70
71              Setting a global value for  modulepath  in  puppet.conf  is  not
72              allowed  (but it can be overridden from the commandline). Please
73              use directory environments instead. If you need to use something
74              other  than the default modulepath of <ACTIVE ENVIRONMENT´S MOD‐
75              ULES DIR>:$basemodulepath, you can set  modulepath  in  environ‐
76              ment.conf.   For  more  info,  see  https://puppet.com/docs/pup
77              pet/latest/environments_about.html
78

ACTIONS

80       build - Build a module release package.
81              SYNOPSIS
82
83              puppet module build [path]
84
85              DESCRIPTION
86
87              Prepares a local module for  release  on  the  Puppet  Forge  by
88              building a ready-to-upload archive file. Note: Module build uses
89              MD5 checksums, which are prohibited on FIPS enabled systems.
90
91              This action uses the metadata.json file in the module  directory
92              to   set   metadata   used   by   the  Forge.  See  https://pup
93              pet.com/docs/puppet/latest/modules_publishing.html   for    more
94              about writing metadata.json files.
95
96              After  being built, the release archive file can be found in the
97              module´s pkg directory.
98
99              RETURNS
100
101              Pathname object representing the path to the release archive.
102
103       changes - Show modified files of an installed module.
104              SYNOPSIS
105
106              puppet module changes path
107
108              DESCRIPTION
109
110              Shows any files in a module that have been modified since it was
111              installed.  This  action  compares  the files on disk to the md5
112              checksums included in the module´s checksums.json or, if that is
113              missing, in metadata.json.
114
115              RETURNS
116
117              Array of strings representing paths of modified files.
118
119       generate - Generate boilerplate for a new module.
120              SYNOPSIS
121
122              puppet module generate [--skip-interview] name
123
124              DESCRIPTION
125
126              Generates boilerplate for a new module by creating the directory
127              structure and files recommended for the Puppet community´s  best
128              practices.
129
130              A module may need additional directories beyond this boilerplate
131              if it provides plugins, files, or templates.
132
133              OPTIONS --skip-interview - Do not attempt to perform a  metadata
134              interview.  Primarily  useful  for automatic execution of puppet
135              module generate.
136
137              RETURNS
138
139              Array of Pathname objects representing paths of generated files.
140
141       install - Install a module from the Puppet Forge or a release archive.
142              SYNOPSIS
143
144              puppet module install [--force | -f] [--target-dir DIR | -i DIR]
145              [--ignore-dependencies]     [--version    VER    |    -v    VER]
146              [--strict-semver] name
147
148              DESCRIPTION
149
150              Installs a module from the Puppet Forge or from  a  release  ar‐
151              chive  file.  Note: Module install uses MD5 checksums, which are
152              prohibited on FIPS enabled systems.
153
154              The specified module will be installed into the directory speci‐
155              fied  with  the --target-dir option, which defaults to the first
156              directory in the modulepath.
157
158              OPTIONS --force | -f - Force overwrite of  existing  module,  if
159              any. Implies --ignore-dependencies.
160
161              --ignore-dependencies  - Do not attempt to install dependencies.
162              Implied by --force.
163
164              --strict-semver  -  Whether  version   ranges   should   exclude
165              pre-release versions
166
167              --target-dir DIR | -i DIR - The directory into which modules are
168              installed; defaults to the first directory in the modulepath.
169
170              Specifying this option will change the  installation  directory,
171              and will use the existing modulepath when checking for dependen‐
172              cies. If you wish to check a different set  of  directories  for
173              dependencies,  you  must  also  use  the --environment or --mod‐
174              ulepath options.
175
176              --version VER | -v VER - Module version to install;  can  be  an
177              exact  version  or a requirement string, eg ´>= 1.0.3´. Defaults
178              to latest version.
179
180              RETURNS
181
182              Pathname object representing the path to the installed module.
183
184       list - List installed modules
185              SYNOPSIS
186
187              puppet module list [--tree] [--strict-semver]
188
189              DESCRIPTION
190
191              Lists the installed puppet  modules.  By  default,  this  action
192              scans  the  modulepath  from puppet.conf´s [main] block; use the
193              --modulepath option to change which directories are scanned.
194
195              The output of this action includes information from the module´s
196              metadata,  including  version numbers and unmet module dependen‐
197              cies.
198
199              OPTIONS --strict-semver - Whether version ranges should  exclude
200              pre-release versions
201
202              --tree - Whether to show dependencies as a tree view
203
204              RETURNS
205
206              hash of paths to module objects
207
208       search - Search the Puppet Forge for a module.
209              SYNOPSIS
210
211              puppet module search search_term
212
213              DESCRIPTION
214
215              Searches  a repository for modules whose names, descriptions, or
216              keywords match the provided search term.
217
218              RETURNS
219
220              Array of module metadata hashes
221
222       uninstall - Uninstall a puppet module.
223              SYNOPSIS
224
225              puppet module uninstall [--force | -f] [--ignore-changes  |  -c]
226              [--version=] [--strict-semver] name
227
228              DESCRIPTION
229
230              Uninstalls  a  puppet  module from the modulepath (or a specific
231              target directory). Note: Module uninstall  uses  MD5  checksums,
232              which are prohibited on FIPS enabled systems.
233
234              OPTIONS  --force | -f - Force the uninstall of an installed mod‐
235              ule even if there are local changes or the possibility of  caus‐
236              ing broken dependencies.
237
238              --ignore-changes  |  -c  - Uninstall an installed module even if
239              there are local changes to it. (Implied by --force.)
240
241              --strict-semver  -  Whether  version   ranges   should   exclude
242              pre-release versions
243
244              --version=  - The version of the module to uninstall. When using
245              this option, a module matching the  specified  version  must  be
246              installed or else an error is raised.
247
248              RETURNS
249
250              Hash  of  module  objects  representing  uninstalled modules and
251              related errors.
252
253       upgrade - Upgrade a puppet module.
254              SYNOPSIS
255
256              puppet module upgrade  [--force  |  -f]  [--ignore-dependencies]
257              [--ignore-changes | -c] [--version=] [--strict-semver] name
258
259              DESCRIPTION
260
261              Upgrades  a  puppet module. Note: Module upgrade uses MD5 check‐
262              sums, which are prohibited on FIPS enabled systems.
263
264              OPTIONS --force | -f - Force the upgrade of an installed  module
265              even  if  there  are local changes or the possibility of causing
266              broken dependencies. Implies --ignore-dependencies.
267
268              --ignore-changes | -c - Upgrade  an  installed  module  even  if
269              there are local changes to it. (Implied by --force.)
270
271              --ignore-dependencies  - Do not attempt to install dependencies.
272              Implied by --force.
273
274              --strict-semver  -  Whether  version   ranges   should   exclude
275              pre-release versions
276
277              --version= - The version of the module to upgrade to.
278
279              RETURNS
280
281              Hash
282

EXAMPLES

284       build
285
286       Build a module release:
287
288       $ puppet module build puppetlabs-apache notice: Building /Users/kelsey‐
289       hightower/puppetlabs-apache for release  Module  built:  /Users/kelsey‐
290       hightower/puppetlabs-apache/pkg/puppetlabs-apache-0.0.1.tar.gz
291
292       Build the module in the current working directory:
293
294       $  cd  /Users/kelseyhightower/puppetlabs-apache  $  puppet module build
295       notice: Building /Users/kelseyhightower/puppetlabs-apache  for  release
296       Module    built:   /Users/kelseyhightower/puppetlabs-apache/pkg/puppet‐
297       labs-apache-0.0.1.tar.gz
298
299       changes
300
301       Show modified files of an installed module:
302
303       $ puppet module changes /etc/puppetlabs/code/modules/vcsrepo/  warning:
304       1 files modified lib/puppet/provider/vcsrepo.rb
305
306       generate
307
308       Generate a new module in the current directory:
309
310       $  puppet  module  generate  puppetlabs-ssh  We  need to create a meta‐
311       data.json file for this module. Please answer the following  questions;
312       if the question is not applicable to this module, feel free to leave it
313       blank.
314
315       Puppet uses Semantic Versioning (semver.org) to version  modules.  What
316       version is this module? [0.1.0] -->
317
318       Who wrote this module? [puppetlabs] -->
319
320       What license does this module code fall under? [Apache-2.0] -->
321
322       How would you describe this module in a single sentence? -->
323
324       Where is this module´s source code repository? -->
325
326       Where can others go to learn more about this module? -->
327
328       Where can others go to file issues about this module? -->
329
330       { "name": "puppetlabs-ssh", "version": "0.1.0", "author": "puppetlabs",
331       "summary": null, "license": "Apache-2.0", "source": "", "project_page":
332       null,   "issues_url":   null,  "dependencies":  [  {  "name":  "puppet‐
333       labs-stdlib", "version_requirement": ">= 1.0.0" } ]
334

}

336       About to generate this metadata; continue? [n/Y] -->
337
338       Notice: Generating  module  at  /Users/username/Projects/puppet/puppet‐
339       labs-ssh... Notice: Populating ERB templates... Finished; module gener‐
340       ated in puppetlabs-ssh.  puppetlabs-ssh/manifests  puppetlabs-ssh/mani‐
341       fests/init.pp   puppetlabs-ssh/metadata.json   puppetlabs-ssh/README.md
342       puppetlabs-ssh/spec     puppetlabs-ssh/spec/spec_helper.rb      puppet‐
343       labs-ssh/tests puppetlabs-ssh/tests/init.pp
344
345       install
346
347       Install a module:
348
349       $  puppet  module  install puppetlabs-vcsrepo Preparing to install into
350       /etc/puppetlabs/code/modules ... Downloading from https://forgeapi.pup
351       pet.com   ...   Installing   --   do  not  interrupt  ...  /etc/puppet‐
352       labs/code/modules └── puppetlabs-vcsrepo (v0.0.4)
353
354       Install a module to a specific environment:
355
356       $ puppet module install  puppetlabs-vcsrepo  --environment  development
357       Preparing  to  install  into /etc/puppetlabs/code/environments/develop‐
358       ment/modules  ...  Downloading  from  https://forgeapi.puppet.com   ...
359       Installing   --  do  not  interrupt  ...  /etc/puppetlabs/code/environ‐
360       ments/development/modules └── puppetlabs-vcsrepo (v0.0.4)
361
362       Install a specific module version:
363
364       $ puppet  module  install  puppetlabs-vcsrepo  -v  0.0.4  Preparing  to
365       install    into    /etc/puppetlabs/modules    ...    Downloading   from
366       https://forgeapi.puppet.com ... Installing  --  do  not  interrupt  ...
367       /etc/puppetlabs/code/modules └── puppetlabs-vcsrepo (v0.0.4)
368
369       Install a module into a specific directory:
370
371       $  puppet  module  install puppetlabs-vcsrepo --target-dir=/opt/puppet‐
372       labs/puppet/modules  Preparing  to  install  into  /opt/puppetlabs/pup‐
373       pet/modules   ...   Downloading  from  https://forgeapi.puppet.com  ...
374       Installing -- do not interrupt ...  /opt/puppetlabs/puppet/modules  └──
375       puppetlabs-vcsrepo (v0.0.4)
376
377       Install  a  module into a specific directory and check for dependencies
378       in other directories:
379
380       $ puppet module  install  puppetlabs-vcsrepo  --target-dir=/opt/puppet‐
381       labs/puppet/modules --modulepath /etc/puppetlabs/code/modules Preparing
382       to install into  /opt/puppetlabs/puppet/modules  ...  Downloading  from
383       https://forgeapi.puppet.com  ...  Installing  --  do  not interrupt ...
384       /opt/puppetlabs/puppet/modules └── puppetlabs-vcsrepo (v0.0.4)
385
386       Install a module from a release archive:
387
388       $ puppet module install  puppetlabs-vcsrepo-0.0.4.tar.gz  Preparing  to
389       install   into   /etc/puppetlabs/code/modules   ...   Downloading  from
390       https://forgeapi.puppet.com ... Installing  --  do  not  interrupt  ...
391       /etc/puppetlabs/code/modules └── puppetlabs-vcsrepo (v0.0.4)
392
393       Install a module from a release archive and ignore dependencies:
394
395       $ puppet module install puppetlabs-vcsrepo-0.0.4.tar.gz --ignore-depen‐
396       dencies Preparing  to  install  into  /etc/puppetlabs/code/modules  ...
397       Installing  --  do  not  interrupt ... /etc/puppetlabs/code/modules └──
398       puppetlabs-vcsrepo (v0.0.4)
399
400       list
401
402       List installed modules:
403
404       $  puppet  module  list  /etc/puppetlabs/code/modules  ├──  bodepd-cre‐
405       ate_resources  (v0.0.1)  ├──  puppetlabs-bacula  (v0.0.2)  ├──  puppet‐
406       labs-mysql  (v0.0.1)  ├──  puppetlabs-sqlite   (v0.0.1)   └──   puppet‐
407       labs-stdlib   (v2.2.1)   /opt/puppetlabs/puppet/modules   (no   modules
408       installed)
409
410       List installed modules in a tree view:
411
412       $ puppet module list --tree  /etc/puppetlabs/code/modules  └─┬  puppet‐
413       labs-bacula   (v0.0.2)   ├──  puppetlabs-stdlib  (v2.2.1)  ├─┬  puppet‐
414       labs-mysql (v0.0.1) │ └── bodepd-create_resources (v0.0.1) └──  puppet‐
415       labs-sqlite   (v0.0.1)   /opt/puppetlabs/puppet/modules   (no   modules
416       installed)
417
418       List installed modules from a specified environment:
419
420       $ puppet module list --environment production /etc/puppetlabs/code/mod‐
421       ules   ├──   bodepd-create_resources   (v0.0.1)  ├──  puppetlabs-bacula
422       (v0.0.2) ├── puppetlabs-mysql (v0.0.1) ├──  puppetlabs-sqlite  (v0.0.1)
423       └──  puppetlabs-stdlib (v2.2.1) /opt/puppetlabs/puppet/modules (no mod‐
424       ules installed)
425
426       List installed modules from a specified modulepath:
427
428       $  puppet  module  list   --modulepath   /opt/puppetlabs/puppet/modules
429       /opt/puppetlabs/puppet/modules (no modules installed)
430
431       search
432
433       Search the Puppet Forge for a module:
434
435       $ puppet module search puppetlabs NAME DESCRIPTION AUTHOR KEYWORDS bac‐
436       ula This is a generic Apache module @puppetlabs backups
437
438       uninstall
439
440       Uninstall a module:
441
442       $  puppet  module   uninstall   puppetlabs-ssh   Removed   /etc/puppet‐
443       labs/code/modules/ssh (v1.0.0)
444
445       Uninstall a module from a specific directory:
446
447       $  puppet  module  uninstall  puppetlabs-ssh  --modulepath /opt/puppet‐
448       labs/puppet/modules Removed /opt/puppetlabs/puppet/modules/ssh (v1.0.0)
449
450       Uninstall a module from a specific environment:
451
452       $ puppet  module  uninstall  puppetlabs-ssh  --environment  development
453       Removed       /etc/puppetlabs/code/environments/development/modules/ssh
454       (v1.0.0)
455
456       Uninstall a specific version of a module:
457
458       $  puppet  module  uninstall  puppetlabs-ssh  --version  2.0.0  Removed
459       /etc/puppetlabs/code/modules/ssh (v2.0.0)
460
461       upgrade
462
463       upgrade an installed module to the latest version
464
465       $  puppet  module upgrade puppetlabs-apache /etc/puppetlabs/puppet/mod‐
466       ules └── puppetlabs-apache (v1.0.0 -> v2.4.0)
467
468       upgrade an installed module to a specific version
469
470       $ puppet module upgrade puppetlabs-apache --version 2.1.0  /etc/puppet‐
471       labs/puppet/modules └── puppetlabs-apache (v1.0.0 -> v2.1.0)
472
473       upgrade an installed module for a specific environment
474
475       $  puppet module upgrade puppetlabs-apache --environment test /etc/pup‐
476       petlabs/code/environments/test/modules └── puppetlabs-apache (v1.0.0 ->
477       v2.4.0)
478
480       Copyright 2012 by Puppet Inc. Apache 2 license; see COPYING
481
482
483
484Puppet, Inc.                     January 2020                 PUPPET-MODULE(8)
Impressum