puppet-module(8)

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  ac‐
27       ceptable  parameters. A commented list of all configuration options can
28       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  server,  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 primary
50              server. The environment doesn´t  have  to  exist  on  the  local
51              filesystem because the agent fetches it from the primary server.
52              This definition is 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  al‐
72              lowed  (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       changes - Show modified files of an installed module.
81              SYNOPSIS
82
83              puppet module changes path
84
85              DESCRIPTION
86
87              Shows any files in a module that have been modified since it was
88              installed.  This  action  compares  the files on disk to the md5
89              checksums included in the module´s checksums.json or, if that is
90              missing, in metadata.json.
91
92              RETURNS
93
94              Array of strings representing paths of modified files.
95
96       install - Install a module from the Puppet Forge or a release archive.
97              SYNOPSIS
98
99              puppet module install [--force | -f] [--target-dir DIR | -i DIR]
100              [--ignore-dependencies] [--version VER | -v VER] name
101
102              DESCRIPTION
103
104              Installs a module from the Puppet Forge or from  a  release  ar‐
105              chive  file.  Note: Module install uses MD5 checksums, which are
106              prohibited on FIPS enabled systems.
107
108              The specified module will be installed into the directory speci‐
109              fied  with  the --target-dir option, which defaults to the first
110              directory in the modulepath.
111
112              OPTIONS --force | -f - Force overwrite of  existing  module,  if
113              any. Implies --ignore-dependencies.
114
115              --ignore-dependencies  - Do not attempt to install dependencies.
116              Implied by --force.
117
118              --target-dir DIR | -i DIR - The directory into which modules are
119              installed; defaults to the first directory in the modulepath.
120
121              Specifying  this  option will change the installation directory,
122              and will use the existing modulepath when checking for dependen‐
123              cies.  If  you  wish to check a different set of directories for
124              dependencies, you must also  use  the  --environment  or  --mod‐
125              ulepath options.
126
127              --version  VER  |  -v VER - Module version to install; can be an
128              exact version or a requirement string, eg ´>=  1.0.3´.  Defaults
129              to latest version.
130
131              RETURNS
132
133              Pathname object representing the path to the installed module.
134
135       list - List installed modules
136              SYNOPSIS
137
138              puppet module list [--tree]
139
140              DESCRIPTION
141
142              Lists  the  installed  puppet  modules.  By default, this action
143              scans the modulepath from puppet.conf´s [main]  block;  use  the
144              --modulepath option to change which directories are scanned.
145
146              The output of this action includes information from the module´s
147              metadata, including version numbers and unmet  module  dependen‐
148              cies.
149
150              OPTIONS --tree - Whether to show dependencies as a tree view
151
152              RETURNS
153
154              hash of paths to module objects
155
156       uninstall - Uninstall a puppet module.
157              SYNOPSIS
158
159              puppet  module  uninstall [--force | -f] [--ignore-changes | -c]
160              [--version=] name
161
162              DESCRIPTION
163
164              Uninstalls a puppet module from the modulepath  (or  a  specific
165              target  directory).  Note:  Module uninstall uses MD5 checksums,
166              which are prohibited on FIPS enabled systems.
167
168              OPTIONS --force | -f - Force the uninstall of an installed  mod‐
169              ule  even if there are local changes or the possibility of caus‐
170              ing broken dependencies.
171
172              --ignore-changes | -c - Uninstall an installed  module  even  if
173              there are local changes to it. (Implied by --force.)
174
175              --version=  - The version of the module to uninstall. When using
176              this option, a module matching the specified version must be in‐
177              stalled or else an error is raised.
178
179              RETURNS
180
181              Hash  of module objects representing uninstalled modules and re‐
182              lated errors.
183
184       upgrade - Upgrade a puppet module.
185              SYNOPSIS
186
187              puppet module upgrade  [--force  |  -f]  [--ignore-dependencies]
188              [--ignore-changes | -c] [--version=] name
189
190              DESCRIPTION
191
192              Upgrades  a  puppet module. Note: Module upgrade uses MD5 check‐
193              sums, which are prohibited on FIPS enabled systems.
194
195              OPTIONS --force | -f - Force the upgrade of an installed  module
196              even  if  there  are local changes or the possibility of causing
197              broken dependencies. Implies --ignore-dependencies.
198
199              --ignore-changes | -c - Upgrade  an  installed  module  even  if
200              there are local changes to it. (Implied by --force.)
201
202              --ignore-dependencies  - Do not attempt to install dependencies.
203              Implied by --force.
204
205              --version= - The version of the module to upgrade to.
206
207              RETURNS
208
209              Hash
210

EXAMPLES

212       changes
213
214       Show modified files of an installed module:
215
216       $ puppet module changes  /etc/puppet/code/modules/vcsrepo/  warning:  1
217       files modified lib/puppet/provider/vcsrepo.rb
218
219       install
220
221       Install a module:
222
223       $  puppet  module  install puppetlabs-vcsrepo Preparing to install into
224       /etc/puppet/code/modules  ...  Downloading  from  https://forgeapi.pup‐
225       pet.com   ...   Installing   --   do  not  interrupt  ...  /etc/puppet‐
226       labs/code/modules └── puppetlabs-vcsrepo (v0.0.4)
227
228       Install a module to a specific environment:
229
230       $ puppet module install  puppetlabs-vcsrepo  --environment  development
231       Preparing   to   install   into  /etc/puppet/code/environments/develop‐
232       ment/modules ... Downloading from https://forgeapi.puppet.com  ...  In‐
233       stalling  -- do not interrupt ... /etc/puppetlabs/code/environments/de‐
234       velopment/modules └── puppetlabs-vcsrepo (v0.0.4)
235
236       Install a specific module version:
237
238       $ puppet module install puppetlabs-vcsrepo -v 0.0.4  Preparing  to  in‐
239       stall     into    /etc/puppetlabs/modules    ...    Downloading    from
240       https://forgeapi.puppet.com ... Installing  --  do  not  interrupt  ...
241       /etc/puppet/code/modules └── puppetlabs-vcsrepo (v0.0.4)
242
243       Install a module into a specific directory:
244
245       $ puppet module install puppetlabs-vcsrepo --target-dir=/usr/share/pup‐
246       pet/modules Preparing to  install  into  /opt/puppetlabs/puppet/modules
247       ...  Downloading  from https://forgeapi.puppet.com ... Installing -- do
248       not interrupt ... /opt/puppetlabs/puppet/modules └── puppetlabs-vcsrepo
249       (v0.0.4)
250
251       Install  a  module into a specific directory and check for dependencies
252       in other directories:
253
254       $ puppet module install puppetlabs-vcsrepo --target-dir=/usr/share/pup‐
255       pet/modules  --modulepath /etc/puppet/code/modules Preparing to install
256       into    /opt/puppetlabs/puppet/modules     ...     Downloading     from
257       https://forgeapi.puppet.com  ...  Installing  --  do  not interrupt ...
258       /opt/puppetlabs/puppet/modules └── puppetlabs-vcsrepo (v0.0.4)
259
260       Install a module from a release archive:
261
262       $ puppet module install  puppetlabs-vcsrepo-0.0.4.tar.gz  Preparing  to
263       install    into    /etc/puppet/code/modules    ...   Downloading   from
264       https://forgeapi.puppet.com ... Installing  --  do  not  interrupt  ...
265       /etc/puppetlabs/code/modules └── puppetlabs-vcsrepo (v0.0.4)
266
267       Install a module from a release archive and ignore dependencies:
268
269       $ puppet module install puppetlabs-vcsrepo-0.0.4.tar.gz --ignore-depen‐
270       dencies Preparing to  install  into  /etc/puppet/code/modules  ...  In‐
271       stalling  -- do not interrupt ... /etc/puppetlabs/code/modules └── pup‐
272       petlabs-vcsrepo (v0.0.4)
273
274       list
275
276       List installed modules:
277
278       $ puppet module  list  /etc/puppet/code/modules  ├──  bodepd-create_re‐
279       sources  (v0.0.1)  ├──  puppetlabs-bacula (v0.0.2) ├── puppetlabs-mysql
280       (v0.0.1) ├── puppetlabs-sqlite (v0.0.1) └── puppetlabs-stdlib  (v2.2.1)
281       /usr/share/puppet/modules (no modules installed)
282
283       List installed modules in a tree view:
284
285       $  puppet  module  list  --tree  /etc/puppet/code/modules  └─┬  puppet‐
286       labs-bacula  (v0.0.2)  ├──  puppetlabs-stdlib  (v2.2.1)   ├─┬   puppet‐
287       labs-mysql  (v0.0.1) │ └── bodepd-create_resources (v0.0.1) └── puppet‐
288       labs-sqlite (v0.0.1) /usr/share/puppet/modules (no modules installed)
289
290       List installed modules from a specified environment:
291
292       $ puppet module list --environment production  /etc/puppet/code/modules
293       ├── bodepd-create_resources (v0.0.1) ├── puppetlabs-bacula (v0.0.2) ├──
294       puppetlabs-mysql (v0.0.1) ├── puppetlabs-sqlite  (v0.0.1)  └──  puppet‐
295       labs-stdlib (v2.2.1) /usr/share/puppet/modules (no modules installed)
296
297       List installed modules from a specified modulepath:
298
299       $  puppet  module list --modulepath /usr/share/puppet/modules /opt/pup‐
300       petlabs/puppet/modules (no modules installed)
301
302       uninstall
303
304       Uninstall a module:
305
306       $ puppet module uninstall puppetlabs-ssh Removed  /etc/puppet/code/mod‐
307       ules/ssh (v1.0.0)
308
309       Uninstall a module from a specific directory:
310
311       $  puppet  module uninstall puppetlabs-ssh --modulepath /usr/share/pup‐
312       pet/modules Removed /opt/puppetlabs/puppet/modules/ssh (v1.0.0)
313
314       Uninstall a module from a specific environment:
315
316       $ puppet module uninstall puppetlabs-ssh --environment development  Re‐
317       moved /etc/puppet/code/environments/development/modules/ssh (v1.0.0)
318
319       Uninstall a specific version of a module:
320
321       $  puppet  module  uninstall  puppetlabs-ssh  --version  2.0.0  Removed
322       /etc/puppet/code/modules/ssh (v2.0.0)
323
324       upgrade
325
326       upgrade an installed module to the latest version
327
328       $ puppet module upgrade puppetlabs-apache /etc/puppet/modules └──  pup‐
329       petlabs-apache (v1.0.0 -> v2.4.0)
330
331       upgrade an installed module to a specific version
332
333       $  puppet  module  upgrade  puppetlabs-apache --version 2.1.0 /etc/pup‐
334       pet/modules └── puppetlabs-apache (v1.0.0 -> v2.1.0)
335
336       upgrade an installed module for a specific environment
337
338       $ puppet module upgrade puppetlabs-apache --environment test  /etc/pup‐
339       pet/code/environments/test/modules  └──  puppetlabs-apache  (v1.0.0  ->
340       v2.4.0)
341

COPYRIGHT AND LICENSE

343       Copyright 2012 by Puppet Inc. Apache 2 license; see COPYING
344
345
346
347Puppet, Inc.                     October 2022                 PUPPET-MODULE(8)