1PUPPET-MODULE(8) Puppet manual PUPPET-MODULE(8)
2
6 puppet-module - Creates, installs and searches for modules on the Pup‐
7 pet Forge.
8
10 puppet module action [--environment production ] [--modulepath ]
11
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
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 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 --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 --verbose
36 Whether to log verbosely.
37 --debug
39 Whether to log debug information.
40 --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 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 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 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 --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 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
80 build - Build a module release package.
81 SYNOPSIS
82 puppet module build [path]
84 DESCRIPTION
86 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 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 After being built, the release archive file can be found in the
97 module´s pkg directory.
98 RETURNS
100 Pathname object representing the path to the release archive.
102 changes - Show modified files of an installed module.
104 SYNOPSIS
105 puppet module changes path
107 DESCRIPTION
109 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 RETURNS
116 Array of strings representing paths of modified files.
118 generate - Generate boilerplate for a new module.
120 SYNOPSIS
121 puppet module generate [--skip-interview] name
123 DESCRIPTION
125 Generates boilerplate for a new module by creating the directory
127 structure and files recommended for the Puppet community´s best
128 practices.
129 A module may need additional directories beyond this boilerplate
131 if it provides plugins, files, or templates.
132 OPTIONS --skip-interview - Do not attempt to perform a metadata
134 interview. Primarily useful for automatic execution of puppet
135 module generate.
136 RETURNS
138 Array of Pathname objects representing paths of generated files.
140 install - Install a module from the Puppet Forge or a release archive.
142 SYNOPSIS
143 puppet module install [--force | -f] [--target-dir DIR | -i DIR]
145 [--ignore-dependencies] [--version VER | -v VER]
146 [--strict-semver] name
147 DESCRIPTION
149 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 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 OPTIONS --force | -f - Force overwrite of existing module, if
159 any. Implies --ignore-dependencies.
160 --ignore-dependencies - Do not attempt to install dependencies.
162 Implied by --force.
163 --strict-semver - Whether version ranges should exclude
165 pre-release versions
166 --target-dir DIR | -i DIR - The directory into which modules are
168 installed; defaults to the first directory in the modulepath.
169 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 --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 RETURNS
181 Pathname object representing the path to the installed module.
183 list - List installed modules
185 SYNOPSIS
186 puppet module list [--tree] [--strict-semver]
188 DESCRIPTION
190 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 The output of this action includes information from the module´s
196 metadata, including version numbers and unmet module dependen‐
197 cies.
198 OPTIONS --strict-semver - Whether version ranges should exclude
200 pre-release versions
201 --tree - Whether to show dependencies as a tree view
203 RETURNS
205 hash of paths to module objects
207 search - Search the Puppet Forge for a module.
209 SYNOPSIS
210 puppet module search search_term
212 DESCRIPTION
214 Searches a repository for modules whose names, descriptions, or
216 keywords match the provided search term.
217 RETURNS
219 Array of module metadata hashes
221 uninstall - Uninstall a puppet module.
223 SYNOPSIS
224 puppet module uninstall [--force | -f] [--ignore-changes | -c]
226 [--version=] [--strict-semver] name
227 DESCRIPTION
229 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 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 --ignore-changes | -c - Uninstall an installed module even if
239 there are local changes to it. (Implied by --force.)
240 --strict-semver - Whether version ranges should exclude
242 pre-release versions
243 --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 RETURNS
249 Hash of module objects representing uninstalled modules and
251 related errors.
252 upgrade - Upgrade a puppet module.
254 SYNOPSIS
255 puppet module upgrade [--force | -f] [--ignore-dependencies]
257 [--ignore-changes | -c] [--version=] [--strict-semver] name
258 DESCRIPTION
260 Upgrades a puppet module. Note: Module upgrade uses MD5 check‐
262 sums, which are prohibited on FIPS enabled systems.
263 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 --ignore-changes | -c - Upgrade an installed module even if
269 there are local changes to it. (Implied by --force.)
270 --ignore-dependencies - Do not attempt to install dependencies.
272 Implied by --force.
273 --strict-semver - Whether version ranges should exclude
275 pre-release versions
276 --version= - The version of the module to upgrade to.
278 RETURNS
280 Hash
282
284 build
285 Build a module release:
287 $ 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 Build the module in the current working directory:
293 $ 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 changes
300 Show modified files of an installed module:
302 $ puppet module changes /etc/puppetlabs/code/modules/vcsrepo/ warning:
304 1 files modified lib/puppet/provider/vcsrepo.rb
305 generate
307 Generate a new module in the current directory:
309 $ 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 Puppet uses Semantic Versioning (semver.org) to version modules. What
316 version is this module? [0.1.0] -->
317 Who wrote this module? [puppetlabs] -->
319 What license does this module code fall under? [Apache-2.0] -->
321 How would you describe this module in a single sentence? -->
323 Where is this module´s source code repository? -->
325 Where can others go to learn more about this module? -->
327 Where can others go to file issues about this module? -->
329 { "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 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 install
346 Install a module:
348 $ 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 Install a module to a specific environment:
355 $ 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 Install a specific module version:
363 $ 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 Install a module into a specific directory:
370 $ 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 Install a module into a specific directory and check for dependencies
378 in other directories:
379 $ 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 Install a module from a release archive:
387 $ 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 Install a module from a release archive and ignore dependencies:
394 $ 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 list
401 List installed modules:
403 $ 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 List installed modules in a tree view:
411 $ 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 List installed modules from a specified environment:
419 $ 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 List installed modules from a specified modulepath:
427 $ puppet module list --modulepath /opt/puppetlabs/puppet/modules
429 /opt/puppetlabs/puppet/modules (no modules installed)
430 search
432 Search the Puppet Forge for a module:
434 $ puppet module search puppetlabs NAME DESCRIPTION AUTHOR KEYWORDS bac‐
436 ula This is a generic Apache module @puppetlabs backups
437 uninstall
439 Uninstall a module:
441 $ puppet module uninstall puppetlabs-ssh Removed /etc/puppet‐
443 labs/code/modules/ssh (v1.0.0)
444 Uninstall a module from a specific directory:
446 $ puppet module uninstall puppetlabs-ssh --modulepath /opt/puppet‐
448 labs/puppet/modules Removed /opt/puppetlabs/puppet/modules/ssh (v1.0.0)
449 Uninstall a module from a specific environment:
451 $ puppet module uninstall puppetlabs-ssh --environment development
453 Removed /etc/puppetlabs/code/environments/development/modules/ssh
454 (v1.0.0)
455 Uninstall a specific version of a module:
457 $ puppet module uninstall puppetlabs-ssh --version 2.0.0 Removed
459 /etc/puppetlabs/code/modules/ssh (v2.0.0)
460 upgrade
462 upgrade an installed module to the latest version
464 $ puppet module upgrade puppetlabs-apache /etc/puppetlabs/puppet/mod‐
466 ules └── puppetlabs-apache (v1.0.0 -> v2.4.0)
467 upgrade an installed module to a specific version
469 $ puppet module upgrade puppetlabs-apache --version 2.1.0 /etc/puppet‐
471 labs/puppet/modules └── puppetlabs-apache (v1.0.0 -> v2.1.0)
472 upgrade an installed module for a specific environment
474 $ 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
481Puppet, Inc. January 2020 PUPPET-MODULE(8)