Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP

Tools for managing Puppet modules

Fetching latest commit…

Octocat-spinner-32-eaf2f5

Cannot retrieve the latest commit at this time

Octocat-spinner-32 bin
Octocat-spinner-32 lib
Octocat-spinner-32 spec
Octocat-spinner-32 templates
Octocat-spinner-32 vendor
Octocat-spinner-32 .document
Octocat-spinner-32 .gitignore
Octocat-spinner-32 CHANGES.md
Octocat-spinner-32 LICENSE
Octocat-spinner-32 README.markdown
Octocat-spinner-32 Rakefile
Octocat-spinner-32 TODO
Octocat-spinner-32 VERSION
README.markdown

Puppet Module Tool

The Puppet Module Tool, pmt, helps you author, publish, and manage Puppet modules.

Dependencies

To run pmt, you must have the following installed:

Soure code

The source code for this tool is available online at http://github.com/puppetlabs/puppet-module-tool

You can checkout the source code by installing the git distributed version control system and running:

git clone git://github.com/puppetlabs/puppet-module-tool.git

Running

There are a number of ways to run the pmt program:

  1. From a source code checkout: Checkout the source code and from the checkout directory, run:

    alias pmt=$PWD/bin/pmt

  2. From a locally-built gem: Checkout the source code and from the checkout directory, run:

    Build the gem

    rake gem

    Install the file produced by the above command, e.g.:

    sudo gem install pkg/pmt-0.2.4.gem

  3. From an official gem: Install it by running:

    FIXME: THIS DOES NOT WORK, WE HAVEN'T PUBLISHED THE GEM YET!

    sudo gem install pmt

Basics

Display the program's built-in help by running:

pmt help

Display information on a specific command by running a command like:

pmt help install

Many commands will use a specific repository if you pass it to the -r option at the end, like:

pmt search mymodule -r http://forge.puppetlabs.com/

Search for modules

Searching displays modules on the repository that match your query.

For example, search the default repository for modules whose names include the substring mymodule:

pmt search mymodule

Install a module release

Installing a module release from a repository downloads a special archive file. This archive is then automatically unpacked into a new directory under your current directory. You can then add this module directory to your Puppet configuration files to use it.

For example, install the latest release of the module named mymodule written by myuser from the default repository:

pmt install myuser-mymodule

Or install a specific version:

pmt install myuser-mymodule --version=0.0.1

Generate a module

Generating a new module produces a new directory prepopulated with a directory structure and files recommended for Puppet best practices.

For example, generate a new module:

pmt generate myuser-mymodule

The above command will create a new module directory called myuser-mymodule under your current directory with the generated files.

Please read the files in this generated directory for further details.

Build a module release

Building a module release processes the files in your module directory and produces a special archive file that you can share or install.

For example, build a module release from within the module directory:

pmt build

The above command will report where it created the module release archive file.

For example, if this was version 0.0.1 of myuser-mymodule, then this would have created a pkg/myuser-mymodule-0.0.1.tar.gz release file.

The build process reads a Modulefile in your module directory and uses its contents to direct its work.

The Modulefile is a Ruby domain-specific language (DSL).

Here's an example of a Modulefile:

name 'myuser-mymodule'
version '0.0.1'
dependency 'otheruser-othermodule', '1.2.3'

The build process reads the Modulefile and uses it to build a metadata.json file. This generated JSON file is included in the module release archive so that repositories and installers can extract details from your release. Do not edit this metadata.json file yourself because it's clobbered each time during the build process -- you should make all your changes to the Modulefile instead.

All the files in the pkg directory of your module directory are artifacts of the build process. You can delete them when you're done.

Share a module

Sharing a module release with others helps others avoid reinventing the wheel, and encourages them to help with your work by improving it. For every module you share, we hope you'll find many modules by others that will be useful to you.

You can share your modules at http://forge.puppetlabs.com/

Building and sharing a new module version

To build and share a new module version:

  1. Edit the Modulefile and increase the version number.
  2. Run the pmt build as explained in the Build a module release section.
  3. Upload the new release file as explained in the Share a module section.

Cleaning the cache

Modules that you install are saved to a cache within your ~/.puppet directory. This cache can be cleaned out by running:

pmt clean

Deleting a module

The tool does not keep track of what modules you have installed. TO delete a module just delete the directory the module was extracted into.

Get involved

This is new and exciting for us. We have many plans for this and what you see now is just the beginning. If you have ideas, please get in touch. Puppet Labs can be contacted at: info@puppetlabs.com

Technical disclaimer for techies

This tool downloads untrusted code from the Internet. Please read the source code before executing it to avoid surprises. If it breaks, it's not our fault -- although we encourage you to contact the authors, file a bug report and send patches.

Legal disclaimer for lawyers

THE PROGRAM AND MODULES ARE DISTRIBUTED IN THE HOPE THAT THEY WILL BE USEFUL, BUT WITHOUT ANY WARRANTY. THEY ARE PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE PROGRAM OR MODULES PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION.

IN NO EVENT WILL Puppet Labs Inc. BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THIS PROGRAM OR MODULES (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM OR MODULES TO OPERATE WITH ANY OTHER PROGRAMS OR MODULES), EVEN IF Puppet Labs Inc. HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.

License

This software is distributed under the GNU General Public License version 2 or any later version. See the LICENSE file for details.

Copyright

Copyright (C) 2010 Puppet Labs Inc.

Something went wrong with that request. Please try again.