Reboot type and provider
Clone or download
glennsarti Merge pull request #171 from dylanratcliffe/add_wait_function
(MODULES-8046) Added function to wait for reboots
Latest commit d4e8444 Oct 15, 2018
Permalink
Failed to load latest commit information.
.github (maint) Add Github Pull Request Template Nov 16, 2017
examples Designate former 'tests' file as examples Dec 1, 2016
lib/puppet (MODULES-8046) Added ability to handle a single node Oct 12, 2018
locales (maint) modulesync 892c4cf Sep 18, 2017
spec (MODULES-8046) Add mocking for Orchestrator Client configuration Oct 12, 2018
tasks Remediated CVE-2018-6508 Feb 15, 2018
.fixtures.yml (MODULES-8046) Added tests for `reboot::wait` Oct 12, 2018
.gitattributes [maint] modulesync e25ca9 - Add locales folder and config.yaml, chang… Mar 27, 2017
.gitignore (MODULES-7403) PDK Convert the module Aug 21, 2018
.pdkignore (MODULES-7403) PDK Convert the module Aug 21, 2018
.project (MODULES-2207) Update Modulesync Jul 10, 2015
.rspec (FM-5972) Update to next modulesync_configs [dedaf10] Dec 19, 2016
.rubocop.yml (MODULES-7403) PDK Convert the module Aug 21, 2018
.rubocop_todo.yml (MODULES-8046) Address test issues Oct 12, 2018
.sync.yml (maint) Remove symlink check in Travis CI Oct 12, 2018
.travis.yml (maint) Remove symlink check in Travis CI Oct 12, 2018
.yardopts (MODULES-7403) PDK Convert the module Aug 21, 2018
CHANGELOG.md (MODULES-6443) Prep for v2.0.0 release Jan 23, 2018
CONTRIBUTING.md (maint) - modulesync 384f4c1 Dec 13, 2017
Gemfile (MODULES-8046) Added tests for `reboot::wait` Oct 12, 2018
LICENSE (MODULES-4098) Sync the rest of the files Jan 20, 2017
MAINTAINERS.md (MODULES-4098) Sync the rest of the files Jan 20, 2017
NOTICE (maint) modulesync 65530a4 Update Travis Jan 3, 2018
README.md (maint) Fixed verison in bolt docs link Oct 15, 2018
Rakefile (MODULES-7403) PDK Convert the module Aug 21, 2018
appveyor.yml (MODULES-7832) Update module for Puppet 6 Oct 10, 2018
metadata.json (MODULES-7832) Update module for Puppet 6 Oct 10, 2018

README.md

reboot

Build Status

Table of Contents

  1. Overview
  2. Module Description - What the reboot module does and why it is useful
  3. Setup - The basics of getting started with reboot
  4. Usage - Configuration options and additional functionality
  5. Reference - An under-the-hood peek at what the module is doing and how
  6. Limitations - OS compatibility, etc.
  7. Development - Guide for contributing to the module

Overview

This module adds a type, and both Windows and generic POSIX providers, for managing node reboots.

Module Description

Some packages require a reboot of the node to complete their installation. Until that reboot is completed, the package might not be fully functional, and other installs might fail. This module provides a resource type to let Puppet perform that reboot, and providers to support Windows and POSIX systems. HP-UX is not supported.

By default, this module only reboots a node in response to another resource being applied --- e.g., after a package install. On Windows nodes, you can also have Puppet check for pending reboots and complete them before applying the next resource in the catalog, by specifying when => pending.

Setup

Setup Requirements

On Windows nodes, the 'shutdown.exe' command must be in the PATH.

On Windows 2003 (non-R2) x64 nodes, KB942589 must be installed.

Beginning with reboot

The reboot module should work right out of the box. To test it, install a package (in this case 'SomePackage') and set up the module to reboot as follows:

package { 'SomePackage':
  ensure          => installed,
  source          => '\\server\share\some_installer.exe',
  install_options => ['/Passive', '/NoRestart'],
}
reboot { 'after':
  subscribe       => Package['SomePackage'],
}

Usage

Complete any pending reboots before installing a package

reboot { 'before':
  when            => pending,
}
package { 'SomePackage':
  ensure          => installed,
  source          => '\\server\share\some_installer.exe',
  install_options => ['/Passive', '/NoRestart'],
  require         => Reboot['before'],
}

Install multiple packages before rebooting

By default, when this module triggers a reboot, it skips any resources in the catalog that have not yet been applied. To apply the entire catalog before rebooting, specify apply => finished. For example, if you have several packages that all require reboots, but will not block each other:

package { 'Microsoft .NET Framework 4.5':
  ensure => installed,
  ...
  notify => Reboot['after_run'],
}
package { 'Microsoft Windows SDK for Windows 7 (7.0)':
  ensure => installed,
  ...
  notify => Reboot['after_run'],
}
reboot { 'after_run':
  apply  => finished,
}

Reboot when certain conditions are met

This usage applies to Windows only.

When using when => pending, use onlyif or unless to specify the reasons for which to reboot.

reboot { 'reboot on file renames':
  when   => 'pending',
  onlyif => 'pending_file_rename_operations'
}

The possible reasons for rebooting are:

  • reboot_required: A reboot has manually been requested through the provider.
  • component_based_servicing: A new component has been installed.
  • windows_auto_update: An automatic update requested a reboot.
  • pending_file_rename_operations: There are files that need to be renamed at the next reboot.
  • package_installer: A software update requested a reboot.
  • package_installer_syswow64: A software update requested a reboot.
  • pending_computer_rename: The computer needs to be renamed.
  • pending_dsc_reboot: DSC has requested a reboot.
  • pending_ccm_reboot: CCM has requested a reboot.

Reference

Type: reboot

The main type of the module, responsible for all its functionality.

Providers

  • windows: Default for :operatingsystem => :windows
  • linux: Deprecated. Use posix instead.
  • posix: Default for :feature => :posix

Features

  • manages_reboot_pending: Detects whether a reboot is pending due to a prior change. If so, reboot the node. (Available with the windows provider.)

Parameters

apply

Optional. Specifies when to apply the reboot. If set to 'immediately', the provider stops applying additional resources and performs the reboot as soon as Puppet finishes syncing. If set to 'finished', it continues applying resources and then performs the reboot at the end of the run. Valid options: 'immediately' and 'finished'. Default value: 'immediately'.

Note: With the default setting of 'immediately', resources further down in the catalog are skipped and recorded as such. (In Puppet versions prior to 3.3.0, they're left out of the report entirely.) The next time Puppet runs, it processes the skipped resources normally, and they might trigger additional reboots.

message

Optional. Provides a message to log when the reboot is performed. Valid options: a string. Default value: undefined.

name

Required. Sets the name of the reboot resource. Valid options: a string.

timeout

Optional. Sets the number of seconds to wait after the Puppet run completes for the reboot to happen. If the timeout is exceeded, the provider cancels the reboot. Valid options: any positive integer. Default value: '60'.

Note: POSIX systems (with the exception of Solaris) only support specifying the timeout as minutes. As such, the value of timeout must be a multiple of 60. Other values will be rounded up to the nearest minute and a warning will be issued.

when

Optional. Specifies how reboots are triggered. If set to 'refreshed', the provider only reboots the node in response to a refresh event from another resource, e.g., installing a package. If set to 'pending', Puppet checks for signs of any pending reboots and completes them before applying the next resource in the catalog. Valid options: 'refreshed' and 'pending'. Default value: 'refreshed'.

Note: For when => pending reboots, Puppet can normally detect a pending reboot based on some specific system conditions (such as the existence of the PendingFileRenameOperations registry key). However, if those conditions aren't resolved after the node reboots, Puppet triggers another reboot. This can lead to a reboot loop.

onlyif

Optional. Applies a pending reboot only for the specified reasons. This can take a single reason or an array of reasons.

See the Reboot when certain conditions are met section for reasons why you might reboot.

unless

Optional. Ignores the specified reasons when checking for a pending reboot. This can take a single reason or an array of reasons.

See the Reboot when certain conditions are met section for reasons why you might reboot.

Function: reboot::wait

This function is intended to be used as part of a plan and allows Bolt to wait for a server to reboot before continuing. This function has no use in normal Puppet code (outside of plans) and will not work.

Here is an example of using this module to reboot servers, wait for them to come back, then check the status of a service:

plan myapp::patch (
  $servers,
  $version,
) {
  # Upgrade the application
  run_task('myapp::upgrade', $servers, { 'version' => $version })

  # Reboot the servers
  run_task('reboot', $servers)

  # Wait for them to come back, this app is slow to shut down so give them
  # 5 min to shut down
  reboot::wait($servers, { 'disconnect_wait' => 300 })

  # Check the status of the service
  return run_task('service', $nodes, {
    'name'   => 'myapp',
    'action' => 'status',
  })
}

Parameters

targets

A TargetSpec object containing all nodes to wait for.

params

A Hash of optional timing parameters, these should be specified as an Integer representing seconds. Available parameters are:

  • disconnect_wait
  • reconnect_wait
  • retry_interval

Limitations

For an extensive list of supported operating systems, see metadata.json

Development

Puppet Labs modules on the Puppet Forge are open projects, and community contributions are essential for keeping them great. We can’t access the huge number of platforms and myriad of hardware, software, and deployment configurations that Puppet is intended to serve.

We want to keep it as easy as possible to contribute changes so that our modules work in your environment. There are a few guidelines that we need contributors to follow so that we can have a chance of keeping on top of things.

For more information, see our module contribution guide.

Contributors

To see who's already involved, see the list of contributors.