Skip to content

Latest commit

 

History

History
437 lines (268 loc) · 16.9 KB

REFERENCE.md

File metadata and controls

437 lines (268 loc) · 16.9 KB
Raw

Reference

Table of Contents

Classes

  • wsus_client: This module manages operating system updates.

Defined types

Functions

Tasks

Classes

wsus_client

This module configures Puppet agents to schedule update downloads and installations from a WSUS server, manage user access to update settings, and configure automatic updates.

Examples

class { 'wsus_client': }

Parameters

The following parameters are available in the wsus_client class:

server_url

Data type: Optional[Variant[Stdlib::HTTPUrl,Boolean]]

Sets the URL at which your WSUS server can be reached. Valid options: fully qualified URL starting with 'http' or 'https', including protocol and port; 'false'; or undef. Default: undef. When set to a URL, Puppet sets the WUServer registry key to this parameter's value and the UseWUServer registry key to '1' (true). If this parameter is set to 'false', Puppet sets UseWUServer to false, disabling WSUS updates on the client. If undefined, Puppet does not manage WUServer or UseWUServer. Even if HTTPS is required for authentication, you can use 'http' URLs instead of 'https'. WSUS automatically switches to an HTTPS connection when required and increments the provided port by 1. For example, if the server_url is 'http://myserver:8530' and the WSUS server requires HTTPS access, the client automatically uses 'https://myserver:8531' to authenticate, then downloads the updates without encryption via the server_url. This performs better than using SSL to encrypt binary downloads. Note: The server_url parameter is central to using wsus_client to manage updates from a WSUS server. While not strictly required to use the class, note that you must manage the WUServer and UseWUServer registry keys yourself if you do not set server_url and enable_status_server.

Default value: undef

enable_status_server

Data type: Optional[Boolean]

Determines whether Puppet also sets the WUStatusServer registry key, which sets the client status reporting destination. Valid options: 'true', 'false', and undef. Default: undef. If this parameter is set to true, Puppet sets the value for the WUStatusServer registry key to the server_url parameter's value. Therefore, when setting this parameter to true, you must also set the server_url parameter to a valid URL or your Puppet run will fail with an error. If enable_status_server is set to 'false', Puppet removes the WUStatusServer registry key. Note: Windows requires the same value for WUStatusServer and WUServer, so wsus_client does not provide an option to set a different status server URL.

Default value: undef

accept_trusted_publisher_certs

Data type: Optional[Boolean]

Determines whether to accept trusted non-Microsoft publisher certificates when checking for updates. Valid options: 'true', 'false', and undef. Default: undef. If 'true', the WSUS server distributes signed non-Microsoft updates. If 'false', the WSUS server only distributes Microsoft updates.

Default value: undef

auto_update_option

Data type: Optional[Variant[Enum['NotifyOnly', 'AutoNotify', 'Scheduled', 'AutoInstall'],Integer[2,5]]]

Sets the automatic update option you would like to use. Valid values: 'NotifyOnly', 'AutoNotify', 'Scheduled', and 'AutoInstall'. You can also refer to these four values using integers 2 through 5, respectively. Default: undef.

See the AUOptions key values on the Microsoft TechNet documentation for detailed descriptions of these options. In summary:

  • 'NotifyOnly': Notifies users before downloading updates.
  • 'AutoNotify': Automatically downloads updates and notifies users.
  • 'Scheduled': Automatically downloads updates and schedules automatic installation.

If set to this value, scheduled_install_day and scheduled_install_hour are required. This parameter must be set to this value to use reschedule_wait_time_minutes. 'AutoInstall': Requires fully automatic updates that users can configure if allowed.

Default value: undef

auto_install_minor_updates

Data type: Optional[Boolean]

Determines whether to silently install minor updates automatically. Valid options: 'true', 'false', and undef. If 'true', Windows installs minor updates without user interaction. If 'false', Windows treats them as any other update, which depends on other settings such as auto_update_option.

Default value: undef

detection_frequency_hours

Data type: Optional[Variant[Integer[1,22],Boolean]]

Sets an interval in hours for clients to check for updates. Valid values: integers 1 through 22. Default: undef. If this enabled parameter has a valid value, Puppet sets the DetectionFrequency registry key to its value and the DetectionFrequencyEnabled Boolean registry key to 'true'. Otherwise, Puppet sets DetectionFrequencyEnabled to 'false' and Windows ignores the value of DetectionFrequency, falling back to the Windows default value of 22 hours.

Default value: undef

disable_windows_update_access

Data type: Optional[Boolean]

Determines whether non-administrators can access Windows Update. Valid options: 'true' (disable access), 'false' (enable access), and undef. Default: undef.

Default value: undef

elevate_non_admins

Data type: Optional[Boolean]

Determines which security groups can approve or refuse updates. Valid options: 'true', 'false', and undef. Default: undef. If 'true', members of the Users group can approve or refuse updates. If 'false', only members of the Administrators group can approve or refuse updates.

Default value: undef

no_auto_reboot_with_logged_on_users

Data type: Optional[Boolean]

Determines whether to automatically reboot while a user is logged in to the client. Valid options: 'true', 'false', and undef. Default: undef. If 'true', Windows will not restart the client after installing updates, even if a reboot is required to finish installing the update. If 'false', Windows notifies the user that the client will restart 15 minutes after installing an update that requires a reboot.

Default value: undef

no_auto_update

Data type: Optional[Boolean]

Disables automatic updates. Valid options: 'true', 'false' (automatic updates enabled), and undef. Default: undef. Windows disables automatic updates when this parameter is set to 'true' and enables them if it's set to 'false'.

Default value: undef

reboot_relaunch_timeout_minutes

Data type: Optional[Variant[Integer[1,1440],Boolean]]

Sets a delay in minutes to wait before attempting to reboot after installing an update that requires one. Valid values: integers 1 through 1440. Default: undef. If this enabled parameter has a valid value, Puppet sets the RebootRelaunchTimeout registry key to its value and the RebootRelaunchTimeoutEnabled Boolean registry key to 'true'. Otherwise, Puppet sets RebootRelaunchTimeoutEnabled to 'false' and Windows ignores the value of RebootRelaunchTimeout, falling back to the Windows default value of 10 minutes.

Default value: undef

reboot_warning_timeout_minutes

Data type: Optional[Variant[Integer[1,30],Boolean]]

Sets how many minutes users can wait before responding to a prompt to reboot the client after installing an update that requires a reboot. Valid values: integers 1 through 30. Default: undef. If this enabled parameter has a valid value, Puppet sets the RebootWarningTimeout registry key to its value and the RebootWarningTimeoutEnabled Boolean registry key to 'true'. Otherwise, Puppet sets RebootWarningTimeoutEnabled to 'false' and Windows ignores the value of RebootWarningTimeout, falling back to the Windows default value of 5 minutes.

Default value: undef

reschedule_wait_time_minutes

Data type: Optional[Variant[Integer[1,60],Boolean]]

Sets how many minutes the client's automatic update service waits at startup before applying updates from a missed scheduled update. Valid values: integers 1 through 60. Default: undef. This enabled parameter is used only when automatic updates are enabled and auto_update_option is set to 'Scheduled' or '4'. If this parameter is set to a valid value, Puppet sets the RescheduleWaitTime registry key to that value and the RescheduleWaitTimeEnabled Boolean registry key to 'true'. Otherwise, Puppet sets RescheduleWaitTimeEnabled to 'false' and Windows ignores the value of RescheduleWaitTime, falling back to the Windows default behavior of re-attempting installation at the next scheduled update time.

Default value: undef

scheduled_install_day

Data type: Optional[Variant[Enum['Everyday', 'Sunday', 'Monday', 'Tuesday', 'Wednesday','Thursday', 'Friday', 'Saturday'],Integer[0,7]]]

Schedules a day of the week to automatically install updates. Valid values: 'Everyday', 'Sunday', 'Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', and 'Saturday'. You can also refer to these eight values using the integers 0 through 7, respectively. Default: undef. This parameter depends on a valid scheduled_install_hour value and is required when auto_update_option is set to 'Scheduled' or '4'.

Default value: undef

scheduled_install_hour

Data type: Optional[Variant[Integer[0,23],Boolean]]

Schedules an hour of the day to automatically install updates. Valid values: an integer from 0 through 23. Default: undef. This parameter depends on a valid scheduled_install_day value and is required when auto_update_option is set to 'Scheduled' or '4'.

Default value: undef

always_auto_reboot_at_scheduled_time

Data type: Optional[Boolean]

Determines whether to automatically reboot. Valid options: 'true', 'false', and undef. Default: undef.

Default value: undef

always_auto_reboot_at_scheduled_time_minutes

Data type: Optional[Variant[Integer[15,180],Boolean]]

Sets the timer to warning a signed-in user that a restart is going to occur. Valid values: integers 15 through 180. Default: undef. When the timer runs out, the restart will proceed even if the PC has signed-in users.

Default value: undef

purge_values

Data type: Boolean

Determines whether Puppet purges values of unmanaged registry keys under the WindowsUpdate parent key. Valid options: Boolean. Default: 'false'.

Default value: false

target_group

Data type: Optional[Variant[String,Boolean]]

Sets the client's target group. Valid values: a string. Default: undef. This enabled parameter is only respected when the WSUS server allows clients to modify this setting via the TargetGroup and TargetGroupEnabled registry keys.

Default value: undef

Defined types

wsus_client::setting

Manages wsus_client settings

Parameters

The following parameters are available in the wsus_client::setting defined type:

ensure

Data type: Enum['present', 'absent', 'file']

Specifies whether the setting should exist. Valid options: 'present', 'absent', and 'file'

Default value: 'present'

key

Data type: String

Specifies registry_value

Default value: $title

data

Data type: Optional[Variant[String,Integer,Boolean,Stdlib::HTTPUrl]]

Incoming data

Default value: undef

type

Data type: String

Data type. default value: dword

Default value: 'dword'

has_enabled

Data type: Boolean

Specifies whether the key should be enabled. Boolean value

Default value: true

validate_range

Data type: Optional[Tuple[Integer, Integer]]

Specifies whether the data should be validated as a number in a certain range

Default value: undef

validate_bool

Data type: Boolean

Specifies whether the data should be validated as a boolean value

Default value: false

Functions

parse_auto_update_option

Type: Ruby 3.x API

Note: Valid options for auto_update_option are NotifyOnly|AutoNotify|Scheduled|AutoInstall|2|3|4|5

parse_auto_update_option()

Note: Valid options for auto_update_option are NotifyOnly|AutoNotify|Scheduled|AutoInstall|2|3|4|5

Returns: Integer option auto_update_option as an integer

parse_scheduled_install_day

Type: Ruby 3.x API

Note: Valid options for scheduled_install_day are Everyday|Sunday|Monday|Tuesday|Wednesday|Thursday|Friday|Saturday|0-7

parse_scheduled_install_day()

Note: Valid options for scheduled_install_day are Everyday|Sunday|Monday|Tuesday|Wednesday|Thursday|Friday|Saturday|0-7

Returns: Integer option scheduled_install_day as an integer

validate_in_range

Type: Ruby 3.x API

Validate the incoming value is in a certain range.

validate_in_range()

The validate_in_range function.

Returns: Any Raises an error if the given value fails this validation.

Tasks

update_history

Returns a history of installed Windows Updates.

Supports noop? false

Parameters

detailed

Data type: Optional[Boolean]

Return detailed update information. Default is to return basic information

title

Data type: Optional[String]

Return updates which match the specified regular expression. Default is to all updates

updateid

Data type: Optional[String]

Return updates which the specified Update ID. Default is to all updates

maximumupdates

Data type: Optional[String]

Limit the size of the history returned. Default is to return a maximum of 300 items