Resource Type: exec

NOTE: This page was generated from the Puppet source code on 2018-08-28 06:48:02 -0700 exec —–

• Attributes
• Providers

Description

Executes external commands.

Any command in an exec resource must be able to run multiple times without causing harm — that is, it must be idempotent. There are three main ways for an exec to be idempotent:

• The command itself is already idempotent. (For example, apt-get update.)
• The exec has an onlyif, unless, or creates attribute, which prevents Puppet from running the command unless some condition is met.
• The exec has refreshonly => true, which only allows Puppet to run the command when some other resource is changed. (See the notes on refreshing below.)

A caution: There’s a widespread tendency to use collections of execs to manage resources that aren’t covered by an existing resource type. This works fine for simple tasks, but once your exec pile gets complex enough that you really have to think to understand what’s happening, you should consider developing a custom resource type instead, as it will be much more predictable and maintainable.

Refresh: exec resources can respond to refresh events (via notify, subscribe, or the ~> arrow). The refresh behavior of execs is non-standard, and can be affected by the refresh and refreshonly attributes:

• If refreshonly is set to true, the exec will only run when it receives an event. This is the most reliable way to use refresh with execs.
• If the exec already would have run and receives an event, it will run its command up to two times. (If an onlyif, unless, or creates condition is no longer met after the first run, the second run will not occur.)
• If the exec already would have run, has a refresh command, and receives an event, it will run its normal command, then run its refresh command (as long as any onlyif, unless, or creates conditions are still met after the normal command finishes).
• If the exec would not have run (due to an onlyif, unless, or creates attribute) and receives an event, it still will not run.
• If the exec has noop => true, would otherwise have run, and receives an event from a non-noop resource, it will run once (or run its refresh command instead, if it has one).

In short: If there’s a possibility of your exec receiving refresh events, it becomes doubly important to make sure the run conditions are restricted.

Autorequires: If Puppet is managing an exec’s cwd or the executable file used in an exec’s command, the exec resource will autorequire those files. If Puppet is managing the user that an exec should run as, the exec resource will autorequire that user.

Attributes

exec { 'resource title':
  command     => # (namevar) The actual command to execute.  Must either be...
  creates     => # A file to look for before running the command...
  cwd         => # The directory from which to run the command.  If 
  environment => # An array of any additional environment variables 
  group       => # The group to run the command as.  This seems to...
  logoutput   => # Whether to log command output in addition to...
  onlyif      => # A test command that checks the state of the...
  path        => # The search path used for command execution...
  provider    => # The specific backend to use for this `exec...
  refresh     => # An alternate command to run when the `exec...
  refreshonly => # The command should only be run as a refresh...
  returns     => # The expected exit code(s).  An error will be...
  timeout     => # The maximum time the command should take.  If...
  tries       => # The number of times execution of the command...
  try_sleep   => # The time to sleep in seconds between...
  umask       => # Sets the umask to be used while executing this...
  unless      => # A test command that checks the state of the...
  user        => # The user to run the command as.  Note that if...
  # ...plus any applicable metaparameters.
}

command

(Namevar: If omitted, this attribute’s value defaults to the resource’s title.)

The actual command to execute. Must either be fully qualified or a search path for the command must be provided. If the command succeeds, any output produced will be logged at the instance’s normal log level (usually notice), but if the command fails (meaning its return code does not match the specified code) then any output is logged at the err log level.

(↑ Back to exec attributes)

creates

A file to look for before running the command. The command will only run if the file doesn’t exist.

This parameter doesn’t cause Puppet to create a file; it is only useful if the command itself creates a file.

exec { 'tar -xf /Volumes/nfs02/important.tar':
  cwd     => '/var/tmp',
  creates => '/var/tmp/myfile',
  path    => ['/usr/bin', '/usr/sbin',],
}

In this example, myfile is assumed to be a file inside important.tar. If it is ever deleted, the exec will bring it back by re-extracting the tarball. If important.tar does not actually contain myfile, the exec will keep running every time Puppet runs.

(↑ Back to exec attributes)

cwd

The directory from which to run the command. If this directory does not exist, the command will fail.

(↑ Back to exec attributes)

environment

An array of any additional environment variables you want to set for a command, such as [ 'HOME=/root', 'MAIL=root@example.com']. Note that if you use this to set PATH, it will override the path attribute. Multiple environment variables should be specified as an array.

(↑ Back to exec attributes)

group

The group to run the command as. This seems to work quite haphazardly on different platforms – it is a platform issue not a Ruby or Puppet one, since the same variety exists when running commands as different users in the shell.

(↑ Back to exec attributes)

logoutput

Whether to log command output in addition to logging the exit code. Defaults to on_failure, which only logs the output when the command has an exit code that does not match any value specified by the returns attribute. As with any resource type, the log level can be controlled with the loglevel metaparameter.

Default: on_failure

Allowed values:

• true
• false
• on_failure

(↑ Back to exec attributes)

onlyif

A test command that checks the state of the target system and restricts when the exec can run. If present, Puppet runs this test command first, and only runs the main command if the test has an exit code of 0 (success). For example:

exec { 'logrotate':
  path     => '/usr/bin:/usr/sbin:/bin',
  provider => shell,
  onlyif   => 'test `du /var/log/messages | cut -f1` -gt 100000',
}

This would run logrotate only if that test returns true.

Note that this test command runs with the same provider, path, cwd, user, and group as the main command. If the path isn’t set, you must fully qualify the command’s name.

This parameter can also take an array of commands. For example:

onlyif => ['test -f /tmp/file1', 'test -f /tmp/file2'],

This exec would only run if every command in the array has an exit code of 0 (success).

(↑ Back to exec attributes)

path

The search path used for command execution. Commands must be fully qualified if no path is specified. Paths can be specified as an array or as a ‘:’ separated list.

(↑ Back to exec attributes)

provider

The specific backend to use for this exec resource. You will seldom need to specify this — Puppet will usually discover the appropriate provider for your platform.

Available providers are:

• posix
• shell
• windows

(↑ Back to exec attributes)

refresh

An alternate command to run when the exec receives a refresh event from another resource. By default, Puppet runs the main command again. For more details, see the notes about refresh behavior above, in the description for this resource type.

Note that this alternate command runs with the same provider, path, user, and group as the main command. If the path isn’t set, you must fully qualify the command’s name.

(↑ Back to exec attributes)

refreshonly

The command should only be run as a refresh mechanism for when a dependent object is changed. It only makes sense to use this option when this command depends on some other object; it is useful for triggering an action:

# Pull down the main aliases file
file { '/etc/aliases':
  source => 'puppet://server/module/aliases',
}

# Rebuild the database, but only when the file changes
exec { newaliases:
  path        => ['/usr/bin', '/usr/sbin'],
  subscribe   => File['/etc/aliases'],
  refreshonly => true,
}

Note that only subscribe and notify can trigger actions, not require, so it only makes sense to use refreshonly with subscribe or notify.

Allowed values:

• true
• false

(↑ Back to exec attributes)

returns

(Property: This attribute represents concrete state on the target system.)

The expected exit code(s). An error will be returned if the executed command has some other exit code. Defaults to 0. Can be specified as an array of acceptable exit codes or a single value.

On POSIX systems, exit codes are always integers between 0 and 255.

On Windows, most exit codes should be integers between 0 and 2147483647.

Larger exit codes on Windows can behave inconsistently across different tools. The Win32 APIs define exit codes as 32-bit unsigned integers, but both the cmd.exe shell and the .NET runtime cast them to signed integers. This means some tools will report negative numbers for exit codes above 2147483647. (For example, cmd.exe reports 4294967295 as -1.) Since Puppet uses the plain Win32 APIs, it will report the very large number instead of the negative number, which might not be what you expect if you got the exit code from a cmd.exe session.

Microsoft recommends against using negative/very large exit codes, and you should avoid them when possible. To convert a negative exit code to the positive one Puppet will use, add it to 4294967296.

Default: 0

(↑ Back to exec attributes)

timeout

The maximum time the command should take. If the command takes longer than the timeout, the command is considered to have failed and will be stopped. The timeout is specified in seconds. The default timeout is 300 seconds and you can set it to 0 to disable the timeout.

Default: 300

(↑ Back to exec attributes)

tries

The number of times execution of the command should be tried. This many attempts will be made to execute the command until an acceptable return code is returned. Note that the timeout parameter applies to each try rather than to the complete set of tries.

Default: 1

(↑ Back to exec attributes)

try_sleep

The time to sleep in seconds between ‘tries’.

Default: 0

(↑ Back to exec attributes)

umask

Sets the umask to be used while executing this command

(↑ Back to exec attributes)

unless

A test command that checks the state of the target system and restricts when the exec can run. If present, Puppet runs this test command first, then runs the main command unless the test has an exit code of 0 (success). For example:

exec { '/bin/echo root >> /usr/lib/cron/cron.allow':
  path   => '/usr/bin:/usr/sbin:/bin',
  unless => 'grep root /usr/lib/cron/cron.allow 2>/dev/null',
}

This would add root to the cron.allow file (on Solaris) unless grep determines it’s already there.

Note that this test command runs with the same provider, path, cwd, user, and group as the main command. If the path isn’t set, you must fully qualify the command’s name.

This parameter can also take an array of commands. For example:

unless => ['test -f /tmp/file1', 'test -f /tmp/file2'],

This exec would only run if every command in the array has a non-zero exit code.

(↑ Back to exec attributes)

user

The user to run the command as. Note that if you use this then any error output is not currently captured. This is because of a bug within Ruby. If you are using Puppet to create this user, the exec will automatically require the user, as long as it is specified by name.

Please note that the $HOME environment variable is not automatically set when using this attribute.

(↑ Back to exec attributes)

Providers

posix

Executes external binaries directly, without passing through a shell or performing any interpolation. This is a safer and more predictable way to execute most commands, but prevents the use of globbing and shell built-ins (including control logic like “for” and “if” statements).

• Confined to: feature == posix
• Default for: feature == posix

shell

Passes the provided command through /bin/sh; only available on POSIX systems. This allows the use of shell globbing and built-ins, and does not require that the path to a command be fully-qualified. Although this can be more convenient than the posix provider, it also means that you need to be more careful with escaping; as ever, with great power comes etc. etc.

This provider closely resembles the behavior of the exec type in Puppet 0.25.x.

• Confined to: feature == posix

windows

Execute external binaries on Windows systems. As with the posix provider, this provider directly calls the command with the arguments given, without passing it through a shell or performing any interpolation. To use shell built-ins — that is, to emulate the shell provider on Windows — a command must explicitly invoke the shell:

exec {'echo foo':
  command => 'cmd.exe /c echo "foo"',
}

If no extension is specified for a command, Windows will use the PATHEXT environment variable to locate the executable.

Note on PowerShell scripts: PowerShell’s default restricted execution policy doesn’t allow it to run saved scripts. To run PowerShell scripts, specify the remotesigned execution policy as part of the command:

exec { 'test':
  path    => 'C:/Windows/System32/WindowsPowerShell/v1.0',
  command => 'powershell -executionpolicy remotesigned -file C:/test.ps1',
}

• Confined to: operatingsystem == windows
• Default for: operatingsystem == windows

NOTE: This page was generated from the Puppet source code on 2018-08-28 06:48:02 -0700