.\" generated with Ronn/v0.7.3
.\" http://github.com/rtomayko/ronn/tree/0.7.3
.
.TH "PUPPET\-MODULE" "8" "June 2012" "Puppet Labs, LLC" "Puppet manual"
.
.SH "NAME"
\fBpuppet\-module\fR \- Creates, installs and searches for modules on the Puppet Forge\.
.
.SH "SYNOPSIS"
puppet module \fIaction\fR
.
.SH "DESCRIPTION"
This subcommand can find, install, and manage modules from the Puppet Forge, a repository of user\-contributed Puppet code\. It can also generate empty modules, and prepare locally developed modules for release on the Forge\.
.
.SH "OPTIONS"
Note that any configuration parameter 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, \fBserver\fR is a valid configuration parameter, so you can specify \fB\-\-server <servername>\fR as an argument\.
.
.P
See the configuration file documentation at \fIhttp://docs\.puppetlabs\.com/references/stable/configuration\.html\fR for the full list of acceptable parameters\. A commented list of all configuration options can also be generated by running puppet with \fB\-\-genconfig\fR\.
.
.TP
\-\-mode MODE
The run mode to use for the current action\. Valid modes are \fBuser\fR, \fBagent\fR, and \fBmaster\fR\.
.
.TP
\-\-render\-as FORMAT
The format in which to render output\. The most common formats are \fBjson\fR, \fBs\fR (string), \fByaml\fR, and \fBconsole\fR, but other options such as \fBdot\fR are sometimes available\.
.
.TP
\-\-verbose
Whether to log verbosely\.
.
.TP
\-\-debug
Whether to log debug information\.
.
.SH "ACTIONS"
.
.TP
\fBbuild\fR \- Build a module release package\.
\fBSYNOPSIS\fR
.
.IP
puppet module build \fIpath\fR
.
.IP
\fBDESCRIPTION\fR
.
.IP
Prepares a local module for release on the Puppet Forge by building a ready\-to\-upload archive file\.
.
.IP
This action uses the Modulefile in the module directory to set metadata used by the Forge\. See \fIhttp://links\.puppetlabs\.com/modulefile\fR for more about writing modulefiles\.
.
.IP
After being built, the release archive file can be found in the module\'s \fBpkg\fR directory\.
.
.IP
\fBRETURNS\fR
.
.IP
Pathname object representing the path to the release archive\.
.
.TP
\fBchanges\fR \- Show modified files of an installed module\.
\fBSYNOPSIS\fR
.
.IP
puppet module changes \fIpath\fR
.
.IP
\fBDESCRIPTION\fR
.
.IP
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 metadata\.
.
.IP
\fBRETURNS\fR
.
.IP
Array of strings representing paths of modified files\.
.
.TP
\fBgenerate\fR \- Generate boilerplate for a new module\.
\fBSYNOPSIS\fR
.
.IP
puppet module generate \fIname\fR
.
.IP
\fBDESCRIPTION\fR
.
.IP
Generates boilerplate for a new module by creating the directory structure and files recommended for the Puppet community\'s best practices\.
.
.IP
A module may need additional directories beyond this boilerplate if it provides plugins, files, or templates\.
.
.IP
\fBRETURNS\fR
.
.IP
Array of Pathname objects representing paths of generated files\.
.
.TP
\fBinstall\fR \- Install a module from the Puppet Forge or a release archive\.
\fBSYNOPSIS\fR
.
.IP
puppet module install [\-\-force | \-f] [\-\-target\-dir DIR | \-i DIR] [\-\-ignore\-dependencies] [\-\-modulepath MODULEPATH] [\-\-version VER | \-v VER] [\-\-environment NAME] \fIname\fR
.
.IP
\fBDESCRIPTION\fR
.
.IP
Installs a module from the Puppet Forge or from a release archive file\.
.
.IP
The specified module will be installed into the directory specified with the \fB\-\-target\-dir\fR option, which defaults to /Users/matthaus/\.puppet/modules\.
.
.IP
\fBOPTIONS\fR
.
.IP
\fI\-\-environment NAME\fR \- The target environment to install modules into\. Only applicable if multiple environments (with different modulepaths) have been configured in puppet\.conf\.
.
.IP
\fI\-\-force\fR | \fI\-f\fR \- Force overwrite of existing module, if any\.
.
.IP
\fI\-\-ignore\-dependencies\fR \- Do not attempt to install dependencies\.
.
.IP
\fI\-\-modulepath MODULEPATH\fR \- The list of directories to check for modules\. When installing a new module, this setting determines where the module tool will look for its dependencies\. If the \fB\-\-target dir\fR option is not specified, the first directory in the modulepath will also be used as the install directory\.
.
.IP
When installing a module into an environment whose modulepath is specified in puppet\.conf, you can use the \fB\-\-environment\fR option instead, and its modulepath will be used automatically\.
.
.IP
This setting should be a list of directories separated by the path separator character\. (The path separator is \fB:\fR on Unix\-like platforms and \fB;\fR on Windows\.)
.
.IP
\fI\-\-target\-dir DIR\fR | \fI\-i DIR\fR \- The directory into which modules are installed; defaults to the first directory in the modulepath\.
.
.IP
Specifying this option will change the installation directory, and will use the existing modulepath when checking for dependencies\. If you wish to check a different set of directories for dependencies, you must also use the \fB\-\-environment\fR or \fB\-\-modulepath\fR options\.
.
.IP
\fI\-\-version VER\fR | \fI\-v VER\fR \- Module version to install; can be an exact version or a requirement string, eg \'>= 1\.0\.3\'\. Defaults to latest version\.
.
.IP
\fBRETURNS\fR
.
.IP
Pathname object representing the path to the installed module\.
.
.TP
\fBlist\fR \- List installed modules
\fBSYNOPSIS\fR
.
.IP
puppet module list [\-\-environment NAME] [\-\-modulepath MODULEPATH] [\-\-tree]
.
.IP
\fBDESCRIPTION\fR
.
.IP
Lists the installed puppet modules\. By default, this action scans the modulepath from puppet\.conf\'s \fB[main]\fR block; use the \-\-modulepath option to change which directories are scanned\.
.
.IP
The output of this action includes information from the module\'s metadata, including version numbers and unmet module dependencies\.
.
.IP
\fBOPTIONS\fR
.
.IP
\fI\-\-environment NAME\fR \- Which environments\' modules to list\.
.
.IP
\fI\-\-modulepath MODULEPATH\fR \- Which directories to look for modules in; use the system path separator character (\fB:\fR on Unix\-like systems and \fB;\fR on Windows) to specify multiple directories\.
.
.IP
\fI\-\-tree\fR \- Whether to show dependencies as a tree view
.
.IP
\fBRETURNS\fR
.
.IP
hash of paths to module objects
.
.TP
\fBsearch\fR \- Search the Puppet Forge for a module\.
\fBSYNOPSIS\fR
.
.IP
puppet module search \fIsearch_term\fR
.
.IP
\fBDESCRIPTION\fR
.
.IP
Searches the Puppet Forge for modules whose names, descriptions, or keywords match the provided search term\.
.
.IP
\fBRETURNS\fR
.
.IP
Array of module metadata hashes
.
.TP
\fBuninstall\fR \- Uninstall a puppet module\.
\fBSYNOPSIS\fR
.
.IP
puppet module uninstall [\-\-force | \-f] [\-\-environment NAME] [\-\-version=] [\-\-modulepath=] \fIname\fR
.
.IP
\fBDESCRIPTION\fR
.
.IP
Uninstalls a puppet module from the modulepath (or a specific target directory)\.
.
.IP
\fBOPTIONS\fR
.
.IP
\fI\-\-environment NAME\fR \- The target environment to uninstall modules from\.
.
.IP
\fI\-\-force\fR | \fI\-f\fR \- Force the uninstall of an installed module even if there are local changes or the possibility of causing broken dependencies\.
.
.IP
\fI\-\-modulepath=\fR \- The target directory to search for modules\.
.
.IP
\fI\-\-version=\fR \- 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\.
.
.IP
\fBRETURNS\fR
.
.IP
Hash of module objects representing uninstalled modules and related errors\.
.
.TP
\fBupgrade\fR \- Upgrade a puppet module\.
\fBSYNOPSIS\fR
.
.IP
puppet module upgrade [\-\-force | \-f] [\-\-ignore\-dependencies] [\-\-environment NAME] [\-\-version=] \fIname\fR
.
.IP
\fBDESCRIPTION\fR
.
.IP
Upgrades a puppet module\.
.
.IP
\fBOPTIONS\fR
.
.IP
\fI\-\-environment NAME\fR \- The target environment to search for modules\.
.
.IP
\fI\-\-force\fR | \fI\-f\fR \- Force the upgrade of an installed module even if there are local changes or the possibility of causing broken dependencies\.
.
.IP
\fI\-\-ignore\-dependencies\fR \- Do not attempt to install dependencies
.
.IP
\fI\-\-version=\fR \- The version of the module to upgrade to\.
.
.IP
\fBRETURNS\fR
.
.IP
Hash
.
.SH "EXAMPLES"
\fBbuild\fR
.
.P
Build a module release:
.
.P
$ puppet module build puppetlabs\-apache notice: Building /Users/kelseyhightower/puppetlabs\-apache for release puppetlabs\-apache/pkg/puppetlabs\-apache\-0\.0\.1\.tar\.gz
.
.P
\fBchanges\fR
.
.P
Show modified files of an installed module:
.
.P
$ puppet module changes /etc/puppet/modules/vcsrepo/ warning: 1 files modified lib/puppet/provider/vcsrepo\.rb
.
.P
\fBgenerate\fR
.
.P
Generate a new module in the current directory:
.
.P
$ puppet module generate puppetlabs\-ssh notice: Generating module at /Users/kelseyhightower/puppetlabs\-ssh puppetlabs\-ssh puppetlabs\-ssh/tests puppetlabs\-ssh/tests/init\.pp puppetlabs\-ssh/spec puppetlabs\-ssh/spec/spec_helper\.rb puppetlabs\-ssh/spec/spec\.opts puppetlabs\-ssh/README puppetlabs\-ssh/Modulefile puppetlabs\-ssh/metadata\.json puppetlabs\-ssh/manifests puppetlabs\-ssh/manifests/init\.pp
.
.P
\fBinstall\fR
.
.P
Install a module:
.
.P
$ puppet module install puppetlabs\-vcsrepo Preparing to install into /etc/puppet/modules \.\.\. Downloading from http://forge\.puppetlabs\.com \.\.\. Installing \-\- do not interrupt \.\.\. /etc/puppet/modules └── puppetlabs\-vcsrepo (v0\.0\.4)
.
.P
Install a module to a specific environment:
.
.P
$ puppet module install puppetlabs\-vcsrepo \-\-environment development Preparing to install into /etc/puppet/environments/development/modules \.\.\. Downloading from http://forge\.puppetlabs\.com \.\.\. Installing \-\- do not interrupt \.\.\. /etc/puppet/environments/development/modules └── puppetlabs\-vcsrepo (v0\.0\.4)
.
.P
Install a specific module version:
.
.P
$ puppet module install puppetlabs\-vcsrepo \-v 0\.0\.4 Preparing to install into /etc/puppet/modules \.\.\. Downloading from http://forge\.puppetlabs\.com \.\.\. Installing \-\- do not interrupt \.\.\. /etc/puppet/modules └── puppetlabs\-vcsrepo (v0\.0\.4)
.
.P
Install a module into a specific directory:
.
.P
$ puppet module install puppetlabs\-vcsrepo \-\-target\-dir=/usr/share/puppet/modules Preparing to install into /usr/share/puppet/modules \.\.\. Downloading from http://forge\.puppetlabs\.com \.\.\. Installing \-\- do not interrupt \.\.\. /usr/share/puppet/modules └── puppetlabs\-vcsrepo (v0\.0\.4)
.
.P
Install a module into a specific directory and check for dependencies in other directories:
.
.P
$ puppet module install puppetlabs\-vcsrepo \-\-target\-dir=/usr/share/puppet/modules \-\-modulepath /etc/puppet/modules Preparing to install into /usr/share/puppet/modules \.\.\. Downloading from http://forge\.puppetlabs\.com \.\.\. Installing \-\- do not interrupt \.\.\. /usr/share/puppet/modules └── puppetlabs\-vcsrepo (v0\.0\.4)
.
.P
Install a module from a release archive:
.
.P
$ puppet module install puppetlabs\-vcsrepo\-0\.0\.4\.tar\.gz Preparing to install into /etc/puppet/modules \.\.\. Downloading from http://forge\.puppetlabs\.com \.\.\. Installing \-\- do not interrupt \.\.\. /etc/puppet/modules └── puppetlabs\-vcsrepo (v0\.0\.4)
.
.P
Install a module from a release archive and ignore dependencies:
.
.P
$ puppet module install puppetlabs\-vcsrepo\-0\.0\.4\.tar\.gz \-\-ignore\-dependencies Preparing to install into /etc/puppet/modules \.\.\. Installing \-\- do not interrupt \.\.\. /etc/puppet/modules └── puppetlabs\-vcsrepo (v0\.0\.4)
.
.P
\fBlist\fR
.
.P
List installed modules:
.
.P
$ puppet module list /etc/puppet/modules ├── bodepd\-create_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/share/puppet/modules (no modules installed)
.
.P
List installed modules in a tree view:
.
.P
$ puppet module list \-\-tree /etc/puppet/modules └─┬ puppetlabs\-bacula (v0\.0\.2)
.
.IP "" 4
.
.nf

├── puppetlabs\-stdlib (v2\.2\.1)
├─┬ puppetlabs\-mysql (v0\.0\.1)
│ └── bodepd\-create_resources (v0\.0\.1)
└── puppetlabs\-sqlite (v0\.0\.1)
.
.fi
.
.IP "" 0
.
.P
/usr/share/puppet/modules (no modules installed)
.
.P
List installed modules from a specified environment:
.
.P
$ puppet module list \-\-environment production /etc/puppet/modules ├── bodepd\-create_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/share/puppet/modules (no modules installed)
.
.P
List installed modules from a specified modulepath:
.
.P
$ puppet module list \-\-modulepath /usr/share/puppet/modules /usr/share/puppet/modules (no modules installed)
.
.P
\fBsearch\fR
.
.P
Search the Puppet Forge for a module:
.
.P
$ puppet module search puppetlabs NAME DESCRIPTION AUTHOR KEYWORDS bacula This is a generic Apache module @puppetlabs backups
.
.P
\fBuninstall\fR
.
.P
Uninstall a module:
.
.P
$ puppet module uninstall puppetlabs\-ssh Removed /etc/puppet/modules/ssh (v1\.0\.0)
.
.P
Uninstall a module from a specific directory:
.
.P
$ puppet module uninstall puppetlabs\-ssh \-\-modulepath /usr/share/puppet/modules Removed /usr/share/puppet/modules/ssh (v1\.0\.0)
.
.P
Uninstall a module from a specific environment:
.
.P
$ puppet module uninstall puppetlabs\-ssh \-\-environment development Removed /etc/puppet/environments/development/modules/ssh (v1\.0\.0)
.
.P
Uninstall a specific version of a module:
.
.P
$ puppet module uninstall puppetlabs\-ssh \-\-version 2\.0\.0 Removed /etc/puppet/modules/ssh (v2\.0\.0)
.
.P
\fBupgrade\fR
.
.P
upgrade an installed module to the latest version
.
.P
$ puppet module upgrade puppetlabs\-apache /etc/puppet/modules └── puppetlabs\-apache (v1\.0\.0 \-> v2\.4\.0)
.
.P
upgrade an installed module to a specific version
.
.P
$ puppet module upgrade puppetlabs\-apache \-\-version 2\.1\.0 /etc/puppet/modules └── puppetlabs\-apache (v1\.0\.0 \-> v2\.1\.0)
.
.P
upgrade an installed module for a specific environment
.
.P
$ puppet module upgrade puppetlabs\-apache \-\-environment test /usr/share/puppet/environments/test/modules └── puppetlabs\-apache (v1\.0\.0 \-> v2\.4\.0)
.
.SH "COPYRIGHT AND LICENSE"
Copyright 2012 by Puppet Labs Apache 2 license; see COPYING