puppet-windows_power

Module description

Puppet module for managing Windows hibernation settings, power schemes and power devices (or power request overrides respectively).

Setup, Usage, Reference

Summary:

• use class windows_power to manage Windows power devices (physical, logical and virtual); this wraps the defined type windows_power::device
• use class windows_power::hibernate to manage Windows hibernate settings
• use class windows_power::scheme to manage Windows power scheme
• shipped fact power_devices contains all kind of system's power devices, their various wakeup capabilities and their power request overrides
• shipped fact power_schemes contains the system's power schemes and their activation state

See REFERENCE.md for further details and practical examples.

Special notice for v4.0.0

Version 4.0.0 is a complete rewrite and modernization of the previous module and breaks with configuration compatibility.

It also drops support for legacy Windows systems and removes functionality targeting those legacy systems. If you have any of those systems in place (such as Windows XP or Windows Server 2008) don't update.

Limitations

Due to the nature of Windows' way to configure things, we can't just write a config file with desired settings and tell Windows to apply that (or something similar). As well we're not able to determine the current state of some settings (e.g. the timeouts in a power scheme) at all.

Therefore, some commands are applied with every Puppet run to ensure the desired state. Additionally, it might need more than one Puppet run to achieve the final state.

We know that this is very bad Puppet style and we did our best to keep this as minimal as possible. As well we put a lot of effort into making the module fail-safe (e.g. not configuring the wrong power scheme if a new one was created but hasn't been successfully activated yet) at the cost of "might need more than one run".

This module assumes that your system is not managed by an Active Directory controller. We have no way of testing what happens if your system (or parts of it including the power management) is controlled this way and you should use the AD's capabilities of managing power-things then anyways.

Also note that device names, scheme names and similar are subjected to localization (whyever ...). This means that you will have a device System timer on an English system and a Systemzeitgeber on a German system for example. Configuring devices and overrides in an environment with mixed installation languages is probably quite annoying as you will have to create different profiles for different languages with the corresponding device names.

If you have any ideas, suggestions, improvements ... please get in touch with us.

Development

Development happens on GitHub in the well known way (fork, PR, issue, etc.).

Please feel free to report problems, suggest improvements, drop new ideas or teach us how to handle things better.

Reference

Table of Contents

Classes

• windows_power: class to manage Windows power devices (physical, logical and virtual)
• windows_power::hibernate: class to manage Windows hibernate settings
• windows_power::scheme: class to manage Windows power scheme

Defined types

• windows_power::device: defined type to manage a Windows power device (physical, logical and virtual)

Classes

windows_power

class to manage Windows power devices (physical, logical and virtual)

• See also
  • windows_power::device

Examples

basic usage

class { 'windows_power':
  devices => {
    'HID-compliant mouse (001)' => {
      enable_wake => true
    },
    'wmplayer.exe' => {
      power_request_overrides => {
        process => {
          display  => true,
          awaymode => true
        }
      }
    },
    'Realtek PCIe GbE Family Controller' => {
      enable_wake => false,
      power_request_overrides => {
        driver => {
          display => true,
          system  => true
        }
      }
    }
  }
}

Parameters

The following parameters are available in the windows_power class:

• devices

devices

Data type: Optional[Hash[String[1], Hash[Pattern[/^[a-z][a-z0-9_]*$/], Data, 1], 1]]

hash of devices/drivers/services/tools to manage and what/how

Default value: undef

windows_power::hibernate

class to manage Windows hibernate settings

Examples

disable hibernation system wide

class { 'windows_power::hibernate':
  enable => false
}

enable hibernation with default settings

class { 'windows_power::hibernate':
  enable => true
}

enable and configure hibernation

class { 'windows_power::hibernate':
  enable         => true,
  hiberfile_size => 100,
  hiberfile_type => 'full'
}

Parameters

The following parameters are available in the windows_power::hibernate class:

• enable
• hiberfile_size
• hiberfile_type

enable

Data type: Boolean

enable/disable the hibernate feature

hiberfile_size

Data type: Optional[Integer[40, 100]]

set desired hiberfile size (percentage of total memory, 40-100)

Default value: undef

hiberfile_type

Data type: Optional[Enum['reduced', 'full']]

set desired hiberfile type (reduced/full)

Default value: undef

windows_power::scheme

class to manage Windows power scheme

Examples

activate the "High performance" system scheme

class { 'windows_power::scheme':
  guid => '8c5e7fda-e8bf-4a96-9a85-a6e23a8c635c'
}

activate the "Balanced" system scheme and set some monitor timeouts

class { 'windows_power::scheme':
  guid     => '381b4222-f694-41f0-9685-ff5bb260df2e',
  settings => {
    monitor-timeout-ac => 30,
    monitor-timeout-dc => 10
  }
}

create a custom template inheriting "High performance" and tweak on that

class { 'windows_power::scheme':
  guid     => 'a1582e9e-9c9d-46fd-afdf-4d989292a073',
  label    => 'really full power',
  template => '8c5e7fda-e8bf-4a96-9a85-a6e23a8c635c',
  settings => {
    disk-timeout-ac      => 0,
    disk-timeout-dc      => 0,
    standby-timeout-ac   => 0,
    standby-timeout-dc   => 0,
    hibernate-timeout-ac => 0,
    hibernate-timeout-dc => 0
  }
}

Parameters

The following parameters are available in the windows_power::scheme class:

• guid
• label
• template
• description
• settings

guid

Data type: Pattern[/\A[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\z/]

GUID of the scheme to create/activate; to activate/handle an existing scheme (e.g. the ones provided by the system) don't define a template; to create (and activate and handle) a new scheme (derived from an existing one) define the template.

label

Data type: Optional[String[1]]

desired label/name/title of the scheme (optional, recommended for custom schemes)

Default value: undef

template

Data type: Optional[Pattern[/\A[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\z/]]

GUID of the template scheme to use for creating a new custom scheme (optional); if the template does not exist no action is performed; so it's safe to define a template that will appear later somehow.

Default value: undef

description

Data type: Optional[String[1]]

desired descriptive text of the scheme (optional)

Default value: undef

settings

Data type:

Optional[Hash[Enum[
        'monitor-timeout-ac',
        'monitor-timeout-dc',
        'disk-timeout-ac',
        'disk-timeout-dc',
        'standby-timeout-ac',
        'standby-timeout-dc',
        'hibernate-timeout-ac',
        'hibernate-timeout-dc'
  ], Integer[0], 1, 8]]

settings to change (optional); settings are applied to the active scheme and only if this matches the declared GUID; this way accidential configuration of the wrong scheme is avoided but it might need more than one puppet run to complete all tasks.

Default value: undef

Defined types

windows_power::device

defined type to manage a Windows power device (physical, logical and virtual)

Examples

let your mouse wake the system

windows_power::device { 'HID-compliant mouse (001)':
  enable_wake => true
}

don't allow Windows media player to keep system from turning off the display or from going to away mode

windows_power::device { 'wmplayer.exe':
  power_request_overrides => {
    process => {
      display  => true,
      awaymode => true
    }
  }
}

don't allow your network card to wake the system, keep your display turned on or keep the system active

windows_power::device { 'Realtek PCIe GbE Family Controller':
  enable_wake => false,
  power_request_overrides => {
    driver => {
      display => true,
      system  => true
    }
  }
}

delete all power request overrides for/from vpn service

windows_power::device { 'VPN Service':
  power_request_overrides => {
    service => {
      system  => false
    }
  }
}

Parameters

The following parameters are available in the windows_power::device defined type:

• device
• enable_wake
• power_request_overrides

device

Data type: String[1]

name of the device/driver/service/process to handle, defaulting to resource's title (no need to set this manually); also see the shipped fact power_devices! note that the term "device" covers several things (due to the nature of Windows' power management):

• physical devices build in or connected to the machine (such as a network card or a mouse)
• logical devices or device groups (such as "HID-compliant system controller" or even "Volume (005)")
• drivers or driver groups (such as "High Definition Audio Device")
• services (e.g. your remote management software's service name)
• processes (e.g. "your_media_player.exe")

Default value: $title

enable_wake

Data type: Optional[Boolean]

allow (or prohibit) the device to wake the system from a sleep state; devices capable of waking the system do have $facts['power_devices'][$device]['wake_programmable'] == true; devices currently allowed waking the system do have $facts['power_devices'][$device]['wake_armed'] == true; it's safe to set enable_wake => true even if the device is not able to do; defined type only activates wake-up functionality if the device is reported to be capable of doing so!

Default value: undef

power_request_overrides

Data type: Optional[Hash[Enum['service', 'process', 'driver'], Hash[Enum['display', 'system', 'awaymode'], Boolean, 1, 3], 1, 3]]

set (or delete) one or more power request overrides for the device (see Microsoft documentation about power requests and overrides); note that not defining a request type is similar to setting it to false but not defining any request type means "don't touch the current state"; so explicitly setting (only) false values makes it possible to delete request overrides set outside of Puppet! see examples for clarity.

Default value: undef

Changelog

All notable changes to this project will be documented in this file. Each new release typically also includes the latest modulesync defaults. These should not affect the functionality of the module.

v4.0.0 (2024-05-10)

Full Changelog

This is a complete module rewrite/modernization (almost from scratch, but being inspired by what has been there before).

Beyond the Puppet language modernization (and corresponding module redesign) we can summarize the relevant (and breaking) changes as follows:

• drop support for legacy windows systems
• remove functionality targeting those legacy systems
• rework shell/powershell commands and codes accordingly
• correct datatypes and values to match up-to-date systems
• drop dependency to liamjbennett/puppet-win_facts
• update general dependencies/requirements
• add facts power_schemes and power_devices and structure the module around them

Breaking changes:

• great rework #54 (Lightning-)
• Drop Puppet 6 support #51 (bastelfreak)
• modulesync 2.7.0 and drop puppet 4 #33 (bastelfreak)

Closed issues:

• Settings can only be changed for the currently active scheme #36
• Use in-built Windows Facter facts #9

Merged pull requests:

• drop stdlib dependency #53 (Lightning-)
• Remove duplicate CONTRIBUTING.md file #38 (dhoppe)

v3.0.2 (2018-10-20)

Full Changelog

Merged pull requests:

• modulesync 2.2.0 and allow puppet 6.x #28 (bastelfreak)

v3.0.1 (2018-09-06)

Full Changelog

Merged pull requests:

• allow puppetlabs/stdlib 5.x #25 (bastelfreak)
• Remove docker nodesets #22 (bastelfreak)
• drop EOL OSs; fix puppet version range #21 (bastelfreak)

v3.0.0 (2017-11-17)

Full Changelog

Merged pull requests:

• bump puppet version dependency to >= 4.7.1 \< 6.0.0 #17 (bastelfreak)

v2.0.0 (2017-02-11)

This is the last release with Puppet3 support!

• Drop of ruby187 support!
• Fix several rubocop issues
• rubocop: fix RSpec/ImplicitExpect
• Modulesync

2015-03-23 Release 1.0.0

• Initial module release to voxpupuli

* This Changelog was automatically generated by github_changelog_generator