Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
PUPPET-MODULE(8)		 Puppet	manual		      PUPPET-MODULE(8)

NAME
       puppet-module  -	Creates, installs and searches for modules on the Pup-
       pet Forge.

SYNOPSIS
       puppet module action [--environment production ]	[--modulepath ]

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

OPTIONS
       Note  that any setting 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, server and run_mode	are valid settings, so
       you can specify --server	<servername>, or --run_mode  <runmode>	as  an
       argument.

       See   the  configuration	 file  documentation  at  https://docs.puppet-
       labs.com/references/stable/configuration.html for the full list of  ac-
       ceptable	 parameters. A commented list of all configuration options can
       also be generated by running puppet with	--genconfig.

       --render-as FORMAT
	      The format in which to render output. The	 most  common  formats
	      are  json, s (string), yaml, and console,	but other options such
	      as dot are sometimes available.

       --verbose
	      Whether to log verbosely.

       --debug
	      Whether to log debug information.

       --environment production
	      The environment Puppet is	running	in. For	clients	(e.g.,	puppet
	      agent)  this determines the environment itself, which is used to
	      find modules and much more. For servers  (i.e.,  puppet  master)
	      this  provides the default environment for nodes we know nothing
	      about.

       --modulepath
	      The search path for modules, as a	list of	directories  separated
	      by  the system path separator character. (The POSIX path separa-
	      tor is ':', and the Windows path separator is ';'.)

	      Setting a	global value for modulepath in puppet.conf is not  al-
	      lowed  (but  it  can be overridden from the commandline).	Please
	      use directory environments instead. If you need to use something
	      other  than the default modulepath of <ACTIVE ENVIRONMENT'S MOD-
	      ULES DIR>:$basemodulepath, you can set  modulepath  in  environ-
	      ment.conf.  For  more info, see https://docs.puppetlabs.com/pup-
	      pet/latest/reference/environments.html

ACTIONS
       build - Build a module release package.
	      SYNOPSIS

	      puppet module build [path]

	      DESCRIPTION

	      Prepares a local module for  release  on	the  Puppet  Forge  by
	      building a ready-to-upload archive file.

	      This  action uses	the metadata.json file in the module directory
	      to set metadata used  by	the  Forge.  See  https://docs.puppet-
	      labs.com/puppet/latest/reference/modules_publishing.html	   for
	      more about writing metadata.json files.

	      After being built, the release archive file can be found in  the
	      module's pkg directory.

	      RETURNS

	      Pathname object representing the path to the release archive.

       changes - Show modified files of	an installed module.
	      SYNOPSIS

	      puppet module changes path

	      DESCRIPTION

	      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.

	      RETURNS

	      Array of strings representing paths of modified files.

       generate	- Generate boilerplate for a new module.
	      SYNOPSIS

	      puppet module generate [--skip-interview]	name

	      DESCRIPTION

	      Generates	boilerplate for	a new module by	creating the directory
	      structure	and files recommended for the Puppet community's  best
	      practices.

	      A	module may need	additional directories beyond this boilerplate
	      if it provides plugins, files, or	templates.

	      OPTIONS --skip-interview - Do not	attempt	to perform a  metadata
	      interview.  Primarily  useful  for automatic execution of	puppet
	      module generate.

	      RETURNS

	      Array of Pathname	objects	representing paths of generated	files.

       install - Install a module from the Puppet Forge	or a release archive.
	      SYNOPSIS

	      puppet module install [--force | -f] [--target-dir DIR | -i DIR]
	      [--ignore-dependencies] [--version VER | -v VER] name

	      DESCRIPTION

	      Installs	a  module  from	the Puppet Forge or from a release ar-
	      chive file.

	      The specified module will	be installed into the directory	speci-
	      fied  with  the --target-dir option, which defaults to the first
	      directory	in the modulepath.

	      OPTIONS --force |	-f - Force overwrite of	 existing  module,  if
	      any. Implies --ignore-dependencies.

	      --ignore-dependencies  - Do not attempt to install dependencies.
	      Implied by --force.

	      --target-dir DIR | -i DIR	- The directory	into which modules are
	      installed; defaults to the first directory in the	modulepath.

	      Specifying  this	option will change the installation directory,
	      and will use the existing	modulepath when	checking for dependen-
	      cies.  If	 you  wish to check a different	set of directories for
	      dependencies, you	must also  use	the  --environment  or	--mod-
	      ulepath options.

	      --version	 VER  |	 -v VER	- Module version to install; can be an
	      exact version or a requirement string, eg	'>=  1.0.3'.  Defaults
	      to latest	version.

	      RETURNS

	      Pathname object representing the path to the installed module.

       list - List installed modules
	      SYNOPSIS

	      puppet module list [--tree]

	      DESCRIPTION

	      Lists  the  installed  puppet  modules.  By default, this	action
	      scans the	modulepath from	puppet.conf's [main]  block;  use  the
	      --modulepath option to change which directories are scanned.

	      The output of this action	includes information from the module's
	      metadata,	including version numbers and unmet  module  dependen-
	      cies.

	      OPTIONS --tree - Whether to show dependencies as a tree view

	      RETURNS

	      hash of paths to module objects

       search -	Search the Puppet Forge	for a module.
	      SYNOPSIS

	      puppet module search search_term

	      DESCRIPTION

	      Searches	a repository for modules whose names, descriptions, or
	      keywords match the provided search term.

	      RETURNS

	      Array of module metadata hashes

       uninstall - Uninstall a puppet module.
	      SYNOPSIS

	      puppet module uninstall [--force | -f] [--ignore-changes	|  -c]
	      [--version=] name

	      DESCRIPTION

	      Uninstalls  a  puppet  module from the modulepath	(or a specific
	      target directory).

	      OPTIONS --force |	-f - Force the uninstall of an installed  mod-
	      ule  even	if there are local changes or the possibility of caus-
	      ing broken dependencies.

	      --ignore-changes | -c - Uninstall	an installed  module  even  if
	      there are	local changes to it. (Implied by --force.)

	      --version=  - The	version	of the module to uninstall. When using
	      this option, a module matching the specified version must	be in-
	      stalled or else an error is raised.

	      RETURNS

	      Hash  of module objects representing uninstalled modules and re-
	      lated errors.

       upgrade - Upgrade a puppet module.
	      SYNOPSIS

	      puppet module upgrade  [--force  |  -f]  [--ignore-dependencies]
	      [--ignore-changes	| -c] [--version=] name

	      DESCRIPTION

	      Upgrades a puppet	module.

	      OPTIONS  --force | -f - Force the	upgrade	of an installed	module
	      even if there are	local changes or the  possibility  of  causing
	      broken dependencies. Implies --ignore-dependencies.

	      --ignore-changes	|  -c  -  Upgrade  an installed	module even if
	      there are	local changes to it. (Implied by --force.)

	      --ignore-dependencies - Do not attempt to	install	 dependencies.
	      Implied by --force.

	      --version= - The version of the module to	upgrade	to.

	      RETURNS

	      Hash

EXAMPLES
       build

       Build a module release:

       $ puppet	module build puppetlabs-apache notice: Building	/Users/kelsey-
       hightower/puppetlabs-apache for release	Module	built:	/Users/kelsey-
       hightower/puppetlabs-apache/pkg/puppetlabs-apache-0.0.1.tar.gz

       Build the module	in the current working directory:

       $ cd /Users/kelseyhightower/puppetlabs-apache $ puppet module build no-
       tice:  Building	/Users/kelseyhightower/puppetlabs-apache  for  release
       Module	 built:	  /Users/kelseyhightower/puppetlabs-apache/pkg/puppet-
       labs-apache-0.0.1.tar.gz

       changes

       Show modified files of an installed module:

       $ puppet	module changes /etc/puppetlabs/code/modules/vcsrepo/  warning:
       1 files modified	lib/puppet/provider/vcsrepo.rb

       generate

       Generate	a new module in	the current directory:

       $  puppet  module  generate  puppetlabs-ssh  We	need to	create a meta-
       data.json file for this module. Please answer the following  questions;
       if the question is not applicable to this module, feel free to leave it
       blank.

       Puppet uses Semantic Versioning (semver.org) to version	modules.  What
       version is this module? [0.1.0] -->

       Who wrote this module? [puppetlabs] -->

       What license does this module code fall under? [Apache-2.0] -->

       How would you describe this module in a single sentence?	-->

       Where is	this module's source code repository? -->

       Where can others	go to learn more about this module? -->

       Where can others	go to file issues about	this module? -->

       { "name": "puppetlabs-ssh", "version": "0.1.0", "author": "puppetlabs",
       "summary": null,	"license": "Apache-2.0", "source": "", "project_page":
       null,   "issues_url":   null,  "dependencies":  [  {  "name":  "puppet-
       labs-stdlib", "version_requirement": ">=	1.0.0" } ]

}
       About to	generate this metadata;	continue? [n/Y]	-->

       Notice: Generating  module  at  /Users/username/Projects/puppet/puppet-
       labs-ssh... Notice: Populating ERB templates... Finished; module	gener-
       ated in puppetlabs-ssh.	puppetlabs-ssh/manifests  puppetlabs-ssh/mani-
       fests/init.pp   puppetlabs-ssh/metadata.json   puppetlabs-ssh/README.md
       puppetlabs-ssh/spec     puppetlabs-ssh/spec/spec_helper.rb      puppet-
       labs-ssh/tests puppetlabs-ssh/tests/init.pp

       install

       Install a module:

       $  puppet  module  install puppetlabs-vcsrepo Preparing to install into
       /etc/puppetlabs/code/modules ...	Downloading from https://forgeapi.pup-
       petlabs.com  ...	 Installing  --	 do  not  interrupt  ...  /etc/puppet-
       labs/code/modules aaa puppetlabs-vcsrepo	(v0.0.4)

       Install a module	to a specific environment:

       $ puppet	module install	puppetlabs-vcsrepo  --environment  development
       Preparing  to  install  into /etc/puppetlabs/code/environments/develop-
       ment/modules ...	Downloading from  https://forgeapi.puppetlabs.com  ...
       Installing   --	do  not	 interrupt  ...	 /etc/puppetlabs/code/environ-
       ments/development/modules aaa puppetlabs-vcsrepo	(v0.0.4)

       Install a specific module version:

       $ puppet	module install puppetlabs-vcsrepo -v 0.0.4  Preparing  to  in-
       stall	 into	 /etc/puppetlabs/modules    ...	   Downloading	  from
       https://forgeapi.puppetlabs.com ... Installing -- do not	interrupt  ...
       /etc/puppetlabs/code/modules aaa	puppetlabs-vcsrepo (v0.0.4)

       Install a module	into a specific	directory:

       $  puppet  module  install puppetlabs-vcsrepo --target-dir=/opt/puppet-
       labs/puppet/modules  Preparing  to  install  into  /opt/puppetlabs/pup-
       pet/modules  ...	 Downloading  from https://forgeapi.puppetlabs.com ...
       Installing -- do	not interrupt ...  /opt/puppetlabs/puppet/modules  aaa
       puppetlabs-vcsrepo (v0.0.4)

       Install	a  module into a specific directory and	check for dependencies
       in other	directories:

       $ puppet	module	install	 puppetlabs-vcsrepo  --target-dir=/opt/puppet-
       labs/puppet/modules --modulepath	/etc/puppetlabs/code/modules Preparing
       to install into	/opt/puppetlabs/puppet/modules	...  Downloading  from
       https://forgeapi.puppetlabs.com	... Installing -- do not interrupt ...
       /opt/puppetlabs/puppet/modules aaa puppetlabs-vcsrepo (v0.0.4)

       Install a module	from a release archive:

       $ puppet	module install	puppetlabs-vcsrepo-0.0.4.tar.gz	 Preparing  to
       install	 into	/etc/puppetlabs/code/modules   ...   Downloading  from
       https://forgeapi.puppetlabs.com ... Installing -- do not	interrupt  ...
       /etc/puppetlabs/code/modules aaa	puppetlabs-vcsrepo (v0.0.4)

       Install a module	from a release archive and ignore dependencies:

       $ puppet	module install puppetlabs-vcsrepo-0.0.4.tar.gz --ignore-depen-
       dencies Preparing to install into /etc/puppetlabs/code/modules ...  In-
       stalling	 -- do not interrupt ... /etc/puppetlabs/code/modules aaa pup-
       petlabs-vcsrepo (v0.0.4)

       list

       List installed modules:

       $ puppet	module list /etc/puppetlabs/code/modules aaa bodepd-create_re-
       sources	(v0.0.1)  aaa  puppetlabs-bacula (v0.0.2) aaa puppetlabs-mysql
       (v0.0.1)	aaa puppetlabs-sqlite (v0.0.1) aaa puppetlabs-stdlib  (v2.2.1)
       /opt/puppetlabs/puppet/modules (no modules installed)

       List installed modules in a tree	view:

       $  puppet  module list --tree /etc/puppetlabs/code/modules aaa~ puppet-
       labs-bacula  (v0.0.2)  aaa  puppetlabs-stdlib  (v2.2.1)	aaa~   puppet-
       labs-mysql  (v0.0.1) a aaa bodepd-create_resources (v0.0.1) aaa puppet-
       labs-sqlite (v0.0.1)  /opt/puppetlabs/puppet/modules  (no  modules  in-
       stalled)

       List installed modules from a specified environment:

       $ puppet	module list --environment production /etc/puppetlabs/code/mod-
       ules  aaa  bodepd-create_resources   (v0.0.1)   aaa   puppetlabs-bacula
       (v0.0.2)	 aaa  puppetlabs-mysql (v0.0.1)	aaa puppetlabs-sqlite (v0.0.1)
       aaa puppetlabs-stdlib (v2.2.1) /opt/puppetlabs/puppet/modules (no  mod-
       ules installed)

       List installed modules from a specified modulepath:

       $   puppet   module  list  --modulepath	/opt/puppetlabs/puppet/modules
       /opt/puppetlabs/puppet/modules (no modules installed)

       search

       Search the Puppet Forge for a module:

       $ puppet	module search puppetlabs NAME DESCRIPTION AUTHOR KEYWORDS bac-
       ula This	is a generic Apache module @puppetlabs backups

       uninstall

       Uninstall a module:

       $   puppet   module   uninstall	 puppetlabs-ssh	 Removed  /etc/puppet-
       labs/code/modules/ssh (v1.0.0)

       Uninstall a module from a specific directory:

       $ puppet	 module	 uninstall  puppetlabs-ssh  --modulepath  /opt/puppet-
       labs/puppet/modules Removed /opt/puppetlabs/puppet/modules/ssh (v1.0.0)

       Uninstall a module from a specific environment:

       $  puppet module	uninstall puppetlabs-ssh --environment development Re-
       moved	     /etc/puppetlabs/code/environments/development/modules/ssh
       (v1.0.0)

       Uninstall a specific version of a module:

       $  puppet  module  uninstall  puppetlabs-ssh  --version	2.0.0  Removed
       /etc/puppetlabs/code/modules/ssh	(v2.0.0)

       upgrade

       upgrade an installed module to the latest version

       $ puppet	module upgrade	puppetlabs-apache  /etc/puppetlabs/puppet/mod-
       ules aaa	puppetlabs-apache (v1.0.0 -> v2.4.0)

       upgrade an installed module to a	specific version

       $  puppet module	upgrade	puppetlabs-apache --version 2.1.0 /etc/puppet-
       labs/puppet/modules aaa puppetlabs-apache (v1.0.0 -> v2.1.0)

       upgrade an installed module for a specific environment

       $ puppet	module upgrade puppetlabs-apache --environment test  /etc/pup-
       petlabs/code/environments/test/modules aaa puppetlabs-apache (v1.0.0 ->
       v2.4.0)

COPYRIGHT AND LICENSE
       Copyright 2012 by Puppet	Labs Apache 2 license; see COPYING

Puppet Labs, LLC		   May 2015		      PUPPET-MODULE(8)

NAME | SYNOPSIS | DESCRIPTION | OPTIONS | ACTIONS | EXAMPLES | } | COPYRIGHT AND LICENSE

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=puppet-module&sektion=8&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help