{"id":15022580,"url":"https://github.com/puppetlabs/puppetlabs-reboot","last_synced_at":"2025-04-05T08:07:53.750Z","repository":{"id":7520684,"uuid":"8871577","full_name":"puppetlabs/puppetlabs-reboot","owner":"puppetlabs","description":"Reboot type and provider","archived":false,"fork":false,"pushed_at":"2025-02-04T02:07:52.000Z","size":737,"stargazers_count":25,"open_issues_count":3,"forks_count":82,"subscribers_count":168,"default_branch":"main","last_synced_at":"2025-03-31T03:04:01.558Z","etag":null,"topics":["hacktoberfest","module","supported"],"latest_commit_sha":null,"homepage":"","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/puppetlabs.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":"CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2013-03-19T05:35:15.000Z","updated_at":"2025-01-27T04:42:03.000Z","dependencies_parsed_at":"2023-02-10T15:50:12.387Z","dependency_job_id":"88bdb2af-7984-4b73-bef3-f67ae892fd42","html_url":"https://github.com/puppetlabs/puppetlabs-reboot","commit_stats":{"total_commits":421,"total_committers":84,"mean_commits":5.011904761904762,"dds":0.9097387173396675,"last_synced_commit":"09f2dcf81d5efe3d02b214260d15921f1298291f"},"previous_names":[],"tags_count":30,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/puppetlabs%2Fpuppetlabs-reboot","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/puppetlabs%2Fpuppetlabs-reboot/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/puppetlabs%2Fpuppetlabs-reboot/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/puppetlabs%2Fpuppetlabs-reboot/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/puppetlabs","download_url":"https://codeload.github.com/puppetlabs/puppetlabs-reboot/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247271473,"owners_count":20911586,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["hacktoberfest","module","supported"],"created_at":"2024-09-24T19:58:08.522Z","updated_at":"2025-04-05T08:07:53.724Z","avatar_url":"https://github.com/puppetlabs.png","language":"Ruby","funding_links":[],"categories":[],"sub_categories":[],"readme":"# reboot\n\n#### Table of Contents\n\n1. [Overview](#overview)\n2. [Module Description - What the reboot module does and why it is useful](#module-description)\n3. [Setup - The basics of getting started with reboot](#setup)\n    * [Setup requirements](#setup-requirements)\n    * [Beginning with reboot](#beginning-with-reboot)\n4. [Usage - Configuration options and additional functionality](#usage)\n5. [Reference - An under-the-hood peek at what the module is doing and how](#reference)\n6. [Limitations - OS compatibility, etc.](#limitations)\n7. [License](#license)\n8. [Development - Guide for contributing to the module](#development)\n\n## Overview\n\nThis module adds a type, and both Windows and generic POSIX providers, for managing target reboots.\n\n## Module Description\n\nSome 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.\n\nBy 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 =\u003e pending`.\n\n## Setup\n\n### Setup Requirements\n\nOn Windows targets, the 'shutdown.exe' command must be in the `PATH`.\n\nOn Windows 2003 (non-R2) x64 targets, [KB942589](http://support.microsoft.com/kb/942589) must be installed.\n\n### Beginning with reboot\n\nThe 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:\n\n    package { 'SomePackage':\n      ensure          =\u003e installed,\n      source          =\u003e '\\\\server\\share\\some_installer.exe',\n      install_options =\u003e ['/Passive', '/NoRestart'],\n    }\n    reboot { 'after':\n      subscribe       =\u003e Package['SomePackage'],\n    }\n\n## Usage\n\n### Complete any pending reboots before installing a package\n\n    reboot { 'before':\n      when            =\u003e pending,\n    }\n    package { 'SomePackage':\n      ensure          =\u003e installed,\n      source          =\u003e '\\\\server\\share\\some_installer.exe',\n      install_options =\u003e ['/Passive', '/NoRestart'],\n      require         =\u003e Reboot['before'],\n    }\n\n### Install multiple packages before rebooting\n\nBy 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 =\u003e finished`. For example, if you have several packages that all require reboots, but will not block each other:\n\n    package { 'Microsoft .NET Framework 4.5':\n      ensure =\u003e installed,\n      ...\n      notify =\u003e Reboot['after_run'],\n    }\n    package { 'Microsoft Windows SDK for Windows 7 (7.0)':\n      ensure =\u003e installed,\n      ...\n      notify =\u003e Reboot['after_run'],\n    }\n    reboot { 'after_run':\n      apply  =\u003e finished,\n    }\n\n### Reboot when certain conditions are met\n\nThis usage applies to Windows only. \n\nWhen using `when =\u003e pending`, use `onlyif` or `unless` to specify the reasons for which to reboot.\n\n    reboot { 'reboot on file renames':\n      when   =\u003e 'pending',\n      onlyif =\u003e 'pending_file_rename_operations'\n    }\n\nThe possible reasons for rebooting are:\n\n* reboot_required: A reboot has manually been requested through the provider.\n* component_based_servicing: A new component has been installed.\n* windows_auto_update: An automatic update requested a reboot.\n* pending_file_rename_operations: There are files that need to be renamed at the next reboot.\n* package_installer: A software update requested a reboot.\n* package_installer_syswow64: A software update requested a reboot.\n* pending_computer_rename: The computer needs to be renamed.\n* pending_dsc_reboot: DSC has requested a reboot.\n* pending_ccm_reboot: CCM has requested a reboot.\n* pending_domain_join: System has joined domain and is pending a reboot.\n\n## Reference\n\n### Type: reboot\n\nThe main type of the module, responsible for all its functionality.\n\n#### Providers\n\n* `windows`: Default for :operatingsystem =\u003e :windows\n* `linux`: Deprecated. Use `posix` instead.\n* `posix`: Default for :feature =\u003e :posix\n\n#### Features\n\n* `manages_reboot_pending`: Detects whether a reboot is pending due to a prior change. If so, reboot the target. (Available with the `windows` provider.)\n\n#### Parameters\n\n##### `apply`\n\n*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'.\n\n**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.\n\n##### `message`\n\n*Optional.* Provides a message to log when the reboot is performed. Valid options: a string. Default value: undefined.\n\n##### `name`\n\n*Required.* Sets the name of the reboot resource. Valid options: a string.\n\n##### `timeout`\n\n*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'.\n\n**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.\n\n##### `when`\n\n*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'.\n\n**Note:** For `when =\u003e 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.\n\n#### `onlyif`\n\n*Optional.* Applies a pending reboot only for the specified reasons.\nThis can take a single reason or an array of reasons.\n\nSee the [Reboot when certain conditions are met](#reboot-when-certain-conditions-are-met) section for reasons why you might reboot.\n\n#### `unless`\n\n*Optional.* Ignores the specified reasons when checking for a pending reboot.\nThis can take a single reason or an array of reasons.\n\nSee the [Reboot when certain conditions are met](#reboot-when-certain-conditions-are-met) section for reasons why you might reboot.\n\n### Plan: `reboot`\n\nThis plan is intended to be used as part of other [plans](https://puppet.com/docs/bolt/latest/writing_plans.html) and allows Bolt to wait for a server to reboot before continuing. It requires Bolt 1.0+ and/or PE 2019.0+. \n\n**NOTE**: The `nodes` parameters is deprecated in Bolt 2.0, and has been updated here to `targets`.\nThis breaks plans or workflows that explicitly call the `nodes` parameter, however this module is\nstill compatible with Bolt 1.x specifying the `targets` parameter instead.\n\nHere is an example of using this module to reboot servers, wait for them to come back, then check the status of a service:\n\n```puppet\nplan myapp::patch (\n  TargetSpec $servers,\n  TargetSpec $version,\n) {\n  # Upgrade the application\n  run_task('myapp::upgrade', $servers, { 'version' =\u003e $version })\n\n  # Reboot the servers. This app is slow to shut down so give them 5 minutes to reboot.\n  run_plan('reboot', $servers, reconnect_timeout =\u003e 300)\n\n  # Check the status of the service\n  return run_task('service', $servers, {\n    'name'   =\u003e 'myapp',\n    'action' =\u003e 'status',\n  })\n}\n```\n\n#### Return value\n\nThe `reboot` plan returns a ResultSet on success. It also returns a ResultSet if `fail_plan_on_errors` is false.\n\nThe 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.\n\n```\n$plan_result = run_plan('reboot', targets =\u003e $targets)\n$results = case $plan_result {\n  Error:   { $plan_result.details['result_set'] }\n  default: { $plan_result }\n}\n\n$results.ok_set.targets    # Targets that successfully rebooted\n$results.error_set.targets # Targets that did not successfully reboot\n```\n\n#### Parameters\n\n##### `targets`\n\nA `TargetSpec` object containing all targets to wait for.\n\n##### `message`\n\nAn optional message to log when rebooting.\n\n##### `reboot_delay`\n\nHow long (in seconds) to wait before shutting down. Defaults to 0, shutdown immediately.\n\n##### `disconnect_wait`\n\nHow long (in seconds) to wait before checking whether the server has rebooted. Defaults to 1.\n\n##### `reconnect_timeout`\n\nHow long (in seconds) to attempt to reconnect before giving up. Defaults to 180.\n\n##### `retry_interval`\n\nHow long (in seconds) to wait between retries. Defaults to 1.\n\n##### `fail_plan_on_errors`\n\nWhether or not to raise an exception if any targets fail to reboot. Defaults to true.\n\nSetting this value to false allows the return value of a plan to be treated the same way a task return value with `_catch_errors =\u003e true` would be treated.\n\n```puppet\nplan myapp::patch (\n  TargetSpec $targets,\n  String     $version,\n) {\n  $target_objects = get_targets($targets)\n\n  # Upgrade the application\n  $step1_results = run_task('myapp::upgrade', $target_objects,\n    version       =\u003e $version,\n    _catch_errors =\u003e true,\n  )\n\n  # Reboot the servers. This app is slow to shut down so give them 5 minutes to reboot.\n  $step2_results = run_plan('reboot', targets =\u003e $step1_results.ok_set.targets,\n    reconnect_timeout   =\u003e 300\n    fail_plan_on_errors =\u003e false,\n  )\n\n  # Check the status of the service\n  $step3_results = run_task('service', $step2_results.ok_set.targets,\n    name          =\u003e 'myapp',\n    action        =\u003e 'status',\n    _catch_errors =\u003e true,\n  )\n\n  return({\n    'errored-at-step1' =\u003e $step1_results.error_set.names,\n    'errored-at-step2' =\u003e $step2_results.error_set.names,\n    'errored-at-step3' =\u003e $step3_results.error_set.names,\n    'succeeded'        =\u003e $step3_results.ok_set.names,\n  }.filter |$_, $names| { ! $names.empty })\n}\n```\n\n## Limitations\n\nFor an extensive list of supported operating systems, see [metadata.json](https://github.com/puppetlabs/puppetlabs-reboot/blob/main/metadata.json)\n\n## License\n\nThis codebase is licensed under the Apache2.0 licensing, however due to the nature of the codebase the open source dependencies may also use a combination of [AGPL](https://opensource.org/license/agpl-v3/), [BSD-2](https://opensource.org/license/bsd-2-clause/), [BSD-3](https://opensource.org/license/bsd-3-clause/), [GPL2.0](https://opensource.org/license/gpl-2-0/), [LGPL](https://opensource.org/license/lgpl-3-0/), [MIT](https://opensource.org/license/mit/) and [MPL](https://opensource.org/license/mpl-2-0/) Licensing.\n\n## Development\n\nPuppet 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.\n\nWe 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.\n\nFor more information, see our [module contribution guide.](https://docs.puppet.com/forge/contributing.html)\n\n### Contributors\n\nTo see who's already involved, see the [list of contributors.](https://github.com/puppetlabs/puppetlabs-reboot/graphs/contributors)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpuppetlabs%2Fpuppetlabs-reboot","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpuppetlabs%2Fpuppetlabs-reboot","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpuppetlabs%2Fpuppetlabs-reboot/lists"}