reboot

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
   • Setup requirements
   • Beginning 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 target reboots.

Module Description

Some packages require a reboot of the target 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 target in response to another resource being applied --- e.g., after a package install. On Windows targets, 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 targets, the 'shutdown.exe' command must be in the PATH.

On Windows 2003 (non-R2) x64 targets, 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.
• pending_domain_join: System has joined domain and is pending 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 target. (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 target 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 target 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.

Plan: reboot

This plan is intended to be used as part of other plans and allows Bolt to wait for a server to reboot before continuing. It requires Bolt 1.0+ and/or PE 2019.0+.

NOTE: The nodes parameters is deprecated in Bolt 2.0, and has been updated here to targets. This breaks plans or workflows that explicitly call the nodes parameter, however this module is still compatible with Bolt 1.x specifying the targets parameter instead.

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 (
  TargetSpec $servers,
  TargetSpec $version,
) {
  # Upgrade the application
  run_task('myapp::upgrade', $servers, { 'version' => $version })

  # Reboot the servers. This app is slow to shut down so give them 5 minutes to reboot.
  run_plan('reboot', $servers, reconnect_timeout => 300)

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

Return value

The reboot plan returns a ResultSet on success. It also returns a ResultSet if fail_plan_on_errors is false.

The plan may raise an Error if any targets fail to reboot and fail_plan_on_errors is set to true. In that circumstance, the error raised will contain the ResultSet in its details key.

$plan_result = run_plan('reboot', targets => $targets)
$results = case $plan_result {
  Error:   { $plan_result.details['result_set'] }
  default: { $plan_result }
}

$results.ok_set.targets    # Targets that successfully rebooted
$results.error_set.targets # Targets that did not successfully reboot

Parameters

targets

A TargetSpec object containing all targets to wait for.

message

An optional message to log when rebooting.

reboot_delay

How long (in seconds) to wait before shutting down. Defaults to 0, shutdown immediately.

disconnect_wait

How long (in seconds) to wait before checking whether the server has rebooted. Defaults to 1.

reconnect_timeout

How long (in seconds) to attempt to reconnect before giving up. Defaults to 180.

retry_interval

How long (in seconds) to wait between retries. Defaults to 1.

fail_plan_on_errors

Whether or not to raise an exception if any targets fail to reboot. Defaults to true.

Setting this value to false allows the return value of a plan to be treated the same way a task return value with _catch_errors => true would be treated.

plan myapp::patch (
  TargetSpec $targets,
  String     $version,
) {
  $target_objects = get_targets($targets)

  # Upgrade the application
  $step1_results = run_task('myapp::upgrade', $target_objects,
    version       => $version,
    _catch_errors => true,
  )

  # Reboot the servers. This app is slow to shut down so give them 5 minutes to reboot.
  $step2_results = run_plan('reboot', targets => $step1_results.ok_set.targets,
    reconnect_timeout   => 300
    fail_plan_on_errors => false,
  )

  # Check the status of the service
  $step3_results = run_task('service', $step2_results.ok_set.targets,
    name          => 'myapp',
    action        => 'status',
    _catch_errors => true,
  )

  return({
    'errored-at-step1' => $step1_results.error_set.names,
    'errored-at-step2' => $step2_results.error_set.names,
    'errored-at-step3' => $step3_results.error_set.names,
    'succeeded'        => $step3_results.ok_set.names,
  }.filter |$_, $names| { ! $names.empty })
}

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.

Reference

Table of Contents

Resource types

• reboot

Tasks

• init: Reboots a machine
• last_boot_time: Gets the last boot time of a Linux or Windows system
• last_boot_time_nix: Gets the last boot time of a Linux system
• last_boot_time_win: Gets the last boot time of a Windows system
• nix: Reboots a machine
• win: Reboots a machine

Plans

• reboot: Reboots targets and waits for them to be available again.

Resource types

reboot

The reboot type.

Properties

The following properties are available in the reboot type.

when

Valid values: refreshed, pending

When to check for, and if needed, perform a reboot. If pending, then the provider will check if a reboot is pending, and only if needed, reboot the system. If refreshed then the reboot will only be performed in response to a refresh event from another resource, e.g. package.

Default value: refreshed

Parameters

The following parameters are available in the reboot type.

• apply
• message
• name
• onlyif
• provider
• timeout
• unless

apply

Valid values: immediately, finished

When to apply the reboot. If immediately, then the provider will stop applying additional resources and apply the reboot once puppet has finished syncing. If finished, it will continue applying resources and then perform a reboot at the end of the run. The default is immediately.

Default value: immediately

message

Default value: Puppet is rebooting the computer

name

namevar

onlyif

For pending reboots, only reboot if the reboot is pending for one of the supplied reasons.

provider

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

timeout

The amount of time in seconds to wait between the time the reboot is requested and when the reboot is performed. The default timeout is 60 seconds. Note that this time starts once puppet has exited the current run.

Default value: 60

unless

For pending reboots, ignore the supplied reasons when checking pennding reboot

Tasks

init

Reboots a machine

Supports noop? false

Parameters

timeout

Data type: Optional[Variant[Pattern[/^[0-9]*$/],Integer]]

Timeout before shutdown (seconds); enforces a minimum of 3s

message

Data type: Optional[Pattern[/^[^|&]*$/]]

Shutdown message for systems that support it

shutdown_only

Data type: Optional[Boolean]

Only shut the machine down, do not reboot

last_boot_time

Gets the last boot time of a Linux or Windows system

Supports noop? false

last_boot_time_nix

Gets the last boot time of a Linux system

Supports noop? false

last_boot_time_win

Gets the last boot time of a Windows system

Supports noop? false

nix

Reboots a machine

Supports noop? false

Parameters

timeout

Data type: Optional[Integer[3]]

Timeout before shutdown (seconds)

message

Data type: Optional[Pattern[/^[^|&]*$/]]

Shutdown message for systems that support it

shutdown_only

Data type: Optional[Boolean]

Only shut the machine down, do not reboot

win

Reboots a machine

Supports noop? false

Parameters

timeout

Data type: Optional[Integer[3]]

Timeout before shutdown (seconds)

message

Data type: Optional[Pattern[/^[^|&]*$/]]

Shutdown message for systems that support it

shutdown_only

Data type: Optional[Boolean]

Only shut the machine down, do not reboot

Plans

reboot

Reboots targets and waits for them to be available again.

Parameters

The following parameters are available in the reboot plan:

• targets
• message
• reboot_delay
• disconnect_wait
• reconnect_timeout
• retry_interval
• fail_plan_on_errors

targets

Data type: TargetSpec

Targets to reboot.

message

Data type: Optional[String]

Message to log with the reboot (for platforms that support it).

Default value: undef

reboot_delay

Data type: Integer[1]

How long (in seconds) to wait before rebooting. Defaults to 1.

Default value: 1

disconnect_wait

Data type: Integer[0]

How long (in seconds) to wait before checking whether the server has rebooted. Defaults to 10.

Default value: 10

reconnect_timeout

Data type: Integer[0]

How long (in seconds) to attempt to reconnect before giving up. Defaults to 180.

Default value: 180

retry_interval

Data type: Integer[0]

How long (in seconds) to wait between retries. Defaults to 1.

Default value: 1

fail_plan_on_errors

Data type: Boolean

Raise an error if any targets do not successfully reboot. Defaults to true.

Default value: true

Change log

All notable changes to this project will be documented in this file. The format is based on Keep a Changelog and this project adheres to Semantic Versioning.

v4.2.0 (2022-06-06)

Full Changelog

Added

• pdksync - (GH-cat-12) Add Support for Redhat 9 #324 (david22swan)
• pdksync - (FM-8922) - Add Support for Windows 2022 #314 (david22swan)
• pdksync - (IAC-1753) - Add Support for AlmaLinux 8 #309 (david22swan)
• pdksync - (IAC-1751) - Add Support for Rocky 8 #308 (david22swan)

Fixed

• pdksync - (GH-iac-334) Remove Support for Ubuntu 14.04/16.04 #316 (david22swan)
• pdksync - (IAC-1787) Remove Support for CentOS 6 #312 (david22swan)
• pdksync - (IAC-1598) - Remove Support for Debian 8 #307 (david22swan)

v4.1.0 (2021-08-23)

Full Changelog

Added

• pdksync - (IAC-1709) - Add Support for Debian 11 #304 (david22swan)

Fixed

• (MODULES-11149) Modify result of 'last' to remove current time #305 (nmburgan)

v4.0.2 (2021-03-19)

Full Changelog

Fixed

• (MODULES-10963) remove win32-process on Puppet 7 #287 (gimmyxd)

v4.0.1 (2021-03-15)

Full Changelog

Fixed

• Cleanup: Changed to ctrl::sleep() and removed redundant reboot::sleep() function #284 (fetzerms)
• (MODULES-10955) More robust handling of reboot-task output #280 (fetzerms)

v4.0.0 (2021-02-27)

Full Changelog

Changed

• pdksync - (MAINT) Remove SLES 11 support #279 (sanfrancrisko)
• pdksync - (MAINT) Remove RHEL 5 family support #278 (sanfrancrisko)
• pdksync - Remove Puppet 5 from testing and bump minimal version to 6.0.0 #275 (carabasdaniel)

v3.2.0 (2021-01-19)

Full Changelog

Added

• pdksync - (feat) Add support for Puppet 7 #265 (daianamezdrea)

v3.1.0 (2020-11-17)

Full Changelog

Added

• pdksync - (IAC-973) - Update travis/appveyor to run on new default branch main #253 (david22swan)

v3.0.0 (2020-02-27)

Full Changelog

Changed

• (GH-1376) Change $nodes parameter for reboot plan to $targets #223 (beechtom)

v2.4.0 (2020-02-03)

Full Changelog

Added

• Add shutdown_only parameter to tasks #224 (MikaelSmith)
• (MODULES-8201) Add pending reboot due to domain join for windows. #179 (razorbladex401)

v2.3.0 (2019-12-06)

Full Changelog

Added

• (FM-8700) - Addition of Support for CentOs 8 #221 (david22swan)
• pdksync - Add support on Debian10 #218 (lionce)

Fixed

• Fix reboot message for linux hosts #213 (nmaludy)

2.2.0 (2019-07-24)

Full Changelog

v2.2.0 (2019-07-24)

Full Changelog

Added

• (FM-8051) Add RedHat 8 support #207 (eimlav)
• (MODULES-8148) - Add SLES 15 support #191 (eimlav)

Fixed

• Add additional guards for nix process detach #210 (reidmv)
• Fix plan return value #209 (reidmv)
• MODULES-8726: Ensure sbin is in the path #205 (xalimar)
• [MODULES-8718] Check for root or sudo in the reboot task nix.sh script #203 (thilinapiy)
• (MODULES-8717) Fix dependency issue on boltspec #202 (HelenCampbell)

Changelog

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog and this project adheres to Semantic Versioning.

[Unreleased]

[2.1.2] - 2018-12-13

Fixed

• Fix infinite reboot plan wait loop on Windows when reboot takes under a minute (MODULES-8353)
• Mark last_boot_time task implementations as private so they're not listed by Bolt.

[2.1.1] - 2018-12-06

Added

• Use wait_until_available to reduce task runs (BOLT-956)
• Add bash and powershell implementations of reboot task (BOLT-459)
• Support for Puppet 6 (MODULES-7832)
• Add Rubocop to enforce PDK rules (MODULES-5896)
• Add Beaker Testmode Switcher (MODULES-6745)
• Add acceptance-test support for Debian 9, Ubuntu 16.04 and Ubuntu 18.04 (MODULES-7417)

Changed

• Update limitations in README (MODULES-7634)
• Convert module to PDK format (MODULES-7403)
• Use Beaker 4 (MODULES-7658)

Fixed

• Fix conditionals in Windows provider (MODULES-3975)

Removed

• Support for SLES 5 and Debian 7 (FM-6968)

Security

• Fix CVE-2018-6508

[2.0.0] - 2018-01-23

Added

• Support for Puppet 5
• Add a Puppet Task for performing on-demand reboots (MODULES5804)
• Add capability to reboot a Windows machine if specific conditions are met via the onlyif parameter (MODULES-4328)
• Add capability to prevent a reboot resource from rebooting a Windows machine if specific conditions are met via the unless parameter (MODULES-4328)

Fixed

• Converted test framework from Beaker to Beaker-RSpec (MODULES-5977)

Removed

• Ended support for Puppet 3

[1.2.1] - 2015-11-24

Added

• Pending reboot - Allow setting a flag directly on provider (MODULES-2822)

Changed

• Fix use of read method from Registry (MODULES-2804)

[1.2.0] - 2015-10-14

Added

• Pending reboot - detect computer rename (MODULES-2657)
• Pending reboot - Detect DSC pending reboot state (MODULES-2658)
• Pending reboot - Detect CCM pending reboot state (MODULES-2659)

Changed

• Fix Linux provider failing (MODULES-2585)

[1.1.0] - 2015-07-28 - Supported Release 1.1.0

Added

• Add notice when system is scheduling a reboot

Changed

• Move Linux provider to use new POSIX provider
• Fix Unit and Acceptance Test cases

[1.0.0] - 2015-04-15

Added

• Linux support

Changed

• Reboot is now triggered at_exit instead of watching for ruby process to end

Removed

• Prompt for windows reboot
• catalog_apply_timeout parameter

[0.1.9] - 2014-11-11

Changed

• Fixes issues URL in metadata

[0.1.8] - 2014-08-25

Changed

• Fixes for working on x64-native ruby.

[0.1.7] - 2014-07-15

Changed

• Update metadata.json so the module can be uninstalled and upgraded via the puppet module command.

[0.1.6] - 2014-04-15

Changed

• Updated metadata.

[0.1.5] - 2014-03-04

Added

• The version is 0.x but should be considered a 1.x for semantic versioning purposes.

[0.1.4] - 2014-02-07

Changed

• Add a workaround for a ruby bug that can prevent ruby.exe from exiting (PUP-1578)

[0.1.2] - 2013-09-27

Changed

• Never load sample.pp in production

[0.1.1] - 2013-09-27

• Only manage reboot resources on systems where shutdown.exe exists (FM-105)
• Module does not work on Windows 2003 (FM-106)
• Update description in init.pp (PP-433)

[0.1.0] - 2013-09-17

Added

• Initial release of the reboot module

* This Changelog was automatically generated by github_changelog_generator