wsus_client
Version information
This version is compatible with:
- Puppet Enterprise 2019.8.x, 2019.7.x, 2019.5.x, 2019.4.x, 2019.3.x, 2019.2.x, 2019.1.x, 2019.0.x, 2018.1.x, 2017.3.x, 2017.2.x, 2017.1.x, 2016.5.x, 2016.4.x
- Puppet >= 4.7.0 < 7.0.0
Tasks:
- update_history
Start using this module
Add this module to your Puppetfile:
mod 'puppetlabs-wsus_client', '1.1.0'
Learn more about managing modules with a PuppetfileDocumentation
wsus_client
Table of Contents
Module Description
The Windows Server Update Service (WSUS) lets Windows administrators manage operating system updates using their own servers instead of Microsoft's Windows Update servers.
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.
What wsus_client affects
This module modifies registry keys in HKLM\Software\Policies\Microsoft\Windows\WindowsUpdate
. For details about how registry key-driven WSUS configuration works, see the Microsoft TechNet documentation.
Note: Because this module modifies registry keys on clients, it is incompatible with Group Policy Objects that manage the same WSUS settings. Do not use wsus_client to configure WSUS access or automatic updates if you use Group Policies to configure such options on clients, as doing so can lead to unexpected behavior. Instead, consult Microsoft's documentation on configuring automatic updates using Group Policy.
Setup
To use wsus_client, you must have a configured and running WSUS server, and your clients must run Windows Server 2003 or newer. For more information about deploying WSUS, see Microsoft's WSUS Deployment Guide.
To install this module on your Puppet master, run this command:
$ puppet module install [--modulepath <PATH>] puppetlabs/wsus_client
If necessary, use the optional --modulepath
argument to specify your Puppet master's modulepath
.
Beginning with wsus_client
To have the client use a WSUS server and set the server's location, declare the wsus_client
class with the WSUS server's url in the server_url
parameter.
For example, to point a node at a WSUS server located at http://myserver
on port 8530, declare this class:
class { 'wsus_client':
server_url => 'http://myserver:8530',
}
Usage
Schedule updates
To schedule when to retrieve and automatically install updates from a WSUS server, declare the wsus_client
class with a WSUS server_url
as well as the auto_update_option
, scheduled_install_day
, and scheduled_install_hour
parameters.
For example, to schedule weekly updates at 2 a.m. on Tuesdays using a WSUS server at http://myserver:8530
, declare this class:
class { 'wsus_client':
server_url => 'http://myserver:8530',
auto_update_option => "Scheduled",
scheduled_install_day => "Tuesday",
scheduled_install_hour => 2,
}
Clients can report update events to a WSUS status server as defined by the WUStatusServer
registry key, which must have the same value as the WUServer
policy to be valid for automatic updates. For details, see the Microsoft TechNet documentation.
To report the client's status to the WSUS server, use the enable_status_server
parameter. For example, to configure a client to use http://myserver:8530
for both updates and status reporting, declare this class:
class { 'wsus_client':
server_url => 'http://myserver:8530',
enable_status_server => true,
}
Reference
Class: wsus_client
The module's main class is responsible for all its functionality.
Parameters
All parameters are optional unless otherwise noted.
accept_trusted_publisher_certs
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.
auto_install_minor_updates
Determines whether to silently install minor updates automatically. Valid options: 'true', 'false', and undef. Default: 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
.
auto_update_option
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
andscheduled_install_hour
are required. - This parameter must be set to this value to use
reschedule_wait_time_minutes
.
- If set to this value,
- 'AutoInstall': Requires fully automatic updates that users can configure if allowed.
detection_frequency_hours
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.
disable_windows_update_access
Determines whether non-administrators can access Windows Update. Valid options: 'true' (disable access), 'false' (enable access), and undef. Default: undef.
elevate_non_admins
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.
enable_status_server
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.
no_auto_reboot_with_logged_on_users
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.
no_auto_update
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'.
purge_values
Determines whether Puppet purges values of unmanaged registry keys under the WindowsUpdate
parent key. Valid options: Boolean. Default: 'false'.
reboot_relaunch_timeout_minutes
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.
reboot_warning_timeout_minutes
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.
reschedule_wait_time_minutes
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.
scheduled_install_day
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'.
scheduled_install_hour
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'.
server_url
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
.
target_group
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.
Enabled Parameters
Several wsus_client
parameters modify two registry keys, one with a value and the other with a Boolean switch. These parameters, known as enabled parameters, modify both keys only when assigned a value other than 'false'.
For example, if the reschedule_wait_time_minutes
parameter takes a valid integer value from '1' to '60', Puppet sets the RescheduleWaitTimeEnabled
registry key's value to '1' (true). If set to an invalid value or left undefined, Puppet sets the registry key to '0' (false), which disables the feature.
The module's enabled parameters are:
detection_frequency_hours
reboot_relaunch_timeout_minutes
reboot_warning_timeout_minutes
reschedule_wait_time_minutes
target_group
Limitations
This module requires clients running Windows Server 2003 or newer, and a configured and active WSUS server to use all of the module's options except purge_values
. For detailed compatibility information, see the supported module compatibility matrix.
Development
Puppet Inc 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 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. To see who's already involved, see the list of contributors.
What are tasks?
Modules can contain tasks that take action outside of a desired state managed by Puppet. It’s perfect for troubleshooting or deploying one-off changes, distributing scripts to run across your infrastructure, or automating changes that need to happen in a particular order as part of an application deployment.
Tasks in this module release
2018-10-31 - Supported Release 1.1.0
Summary
A feature release for Puppet 5, Puppet6, Windows Server 2016, and Windows Desktop Operating Systems
Bugfixes
- Allow module to be used with Stdlib v6 - MODULES-7705
Features
- Add support for Puppet 5 - MODULES-5144
- Add support for Puppet 6 - MODULES-7833
- Add Testmode Switcher for acceptance testing - MODULES-6735
- Add support for Windows Server 2016 and Windows Desktop Operating Systems - MODULES-4271
- Convert module to PDK format - MODULES-7407
- Add PowerShell task to get Update History - MODULES-7761
2016-12-13 - Supported Release 1.0.3
Summary
Small release supporting Always Automatically Reboot at Scheduled Time setting.
Bugfixes
- Ensure wuaserv service is idempotent - MODULES-2420
Features
- Support AlwaysAutoRebootAtScheduledTimeMinutes - MODULES-3475
- Support AlwaysAutoRebootAtScheduledTime - MODULES-3016
2016-05-03 - Supported Release 1.0.2
Summary
Small release with monior bugfixes
Bugfixes
- Fix links and dependencies in metadata.json
- Fix acceptance tests
2015-12-08 - Supported Release 1.0.1
Summary
Small release for support of newer PE versions.
2015-09-02 - Supported release 1.0.0
Summary
First supported release
Features
- Add metadata for Puppet 4 and PE 2015.2.0
- Update documentation
2015-07-02 - Unsupported release 0.1.3
Summary
Fix the max value of RebootRelaunchTimeout
Features
- Increase RebootRelaunchTimeout to 1440 instead of 440
2015-06-25 - Unsupported release 0.1.2
Summary
Readme fix, metadata addition of puppet versions, and add of CHANGELOG
2015-06-18 - Unsupported release 0.1.1
Summary
Update metadata for project and source urls
2015-06-18 - Initial Release 0.1.0
Summary
Initial release to provide user the ability to manage registry keys pertaining to windows update service
Dependencies
- puppetlabs/stdlib (>= 4.6.0 < 6.0.0)
- puppetlabs/registry (>= 1.0.0 < 3.0.0)
Apache License Version 2.0, January 2004 http://www.apache.org/licenses/ TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION 1. Definitions. "License" shall mean the terms and conditions for use, reproduction, and distribution as defined by Sections 1 through 9 of this document. "Licensor" shall mean the copyright owner or entity authorized by the copyright owner that is granting the License. "Legal Entity" shall mean the union of the acting entity and all other entities that control, are controlled by, or are under common control with that entity. For the purposes of this definition, "control" means (i) the power, direct or indirect, to cause the direction or management of such entity, whether by contract or otherwise, or (ii) ownership of fifty percent (50%) or more of the outstanding shares, or (iii) beneficial ownership of such entity. "You" (or "Your") shall mean an individual or Legal Entity exercising permissions granted by this License. "Source" form shall mean the preferred form for making modifications, including but not limited to software source code, documentation source, and configuration files. "Object" form shall mean any form resulting from mechanical transformation or translation of a Source form, including but not limited to compiled object code, generated documentation, and conversions to other media types. "Work" shall mean the work of authorship, whether in Source or Object form, made available under the License, as indicated by a copyright notice that is included in or attached to the work (an example is provided in the Appendix below). "Derivative Works" shall mean any work, whether in Source or Object form, that is based on (or derived from) the Work and for which the editorial revisions, annotations, elaborations, or other modifications represent, as a whole, an original work of authorship. For the purposes of this License, Derivative Works shall not include works that remain separable from, or merely link (or bind by name) to the interfaces of, the Work and Derivative Works thereof. "Contribution" shall mean any work of authorship, including the original version of the Work and any modifications or additions to that Work or Derivative Works thereof, that is intentionally submitted to Licensor for inclusion in the Work by the copyright owner or by an individual or Legal Entity authorized to submit on behalf of the copyright owner. For the purposes of this definition, "submitted" means any form of electronic, verbal, or written communication sent to the Licensor or its representatives, including but not limited to communication on electronic mailing lists, source code control systems, and issue tracking systems that are managed by, or on behalf of, the Licensor for the purpose of discussing and improving the Work, but excluding communication that is conspicuously marked or otherwise designated in writing by the copyright owner as "Not a Contribution." "Contributor" shall mean Licensor and any individual or Legal Entity on behalf of whom a Contribution has been received by Licensor and subsequently incorporated within the Work. 2. Grant of Copyright License. Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable copyright license to reproduce, prepare Derivative Works of, publicly display, publicly perform, sublicense, and distribute the Work and such Derivative Works in Source or Object form. 3. Grant of Patent License. Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable (except as stated in this section) patent license to make, have made, use, offer to sell, sell, import, and otherwise transfer the Work, where such license applies only to those patent claims licensable by such Contributor that are necessarily infringed by their Contribution(s) alone or by combination of their Contribution(s) with the Work to which such Contribution(s) was submitted. If You institute patent litigation against any entity (including a cross-claim or counterclaim in a lawsuit) alleging that the Work or a Contribution incorporated within the Work constitutes direct or contributory patent infringement, then any patent licenses granted to You under this License for that Work shall terminate as of the date such litigation is filed. 4. Redistribution. You may reproduce and distribute copies of the Work or Derivative Works thereof in any medium, with or without modifications, and in Source or Object form, provided that You meet the following conditions: (a) You must give any other recipients of the Work or Derivative Works a copy of this License; and (b) You must cause any modified files to carry prominent notices stating that You changed the files; and (c) You must retain, in the Source form of any Derivative Works that You distribute, all copyright, patent, trademark, and attribution notices from the Source form of the Work, excluding those notices that do not pertain to any part of the Derivative Works; and (d) If the Work includes a "NOTICE" text file as part of its distribution, then any Derivative Works that You distribute must include a readable copy of the attribution notices contained within such NOTICE file, excluding those notices that do not pertain to any part of the Derivative Works, in at least one of the following places: within a NOTICE text file distributed as part of the Derivative Works; within the Source form or documentation, if provided along with the Derivative Works; or, within a display generated by the Derivative Works, if and wherever such third-party notices normally appear. The contents of the NOTICE file are for informational purposes only and do not modify the License. You may add Your own attribution notices within Derivative Works that You distribute, alongside or as an addendum to the NOTICE text from the Work, provided that such additional attribution notices cannot be construed as modifying the License. You may add Your own copyright statement to Your modifications and may provide additional or different license terms and conditions for use, reproduction, or distribution of Your modifications, or for any such Derivative Works as a whole, provided Your use, reproduction, and distribution of the Work otherwise complies with the conditions stated in this License. 5. Submission of Contributions. Unless You explicitly state otherwise, any Contribution intentionally submitted for inclusion in the Work by You to the Licensor shall be under the terms and conditions of this License, without any additional terms or conditions. Notwithstanding the above, nothing herein shall supersede or modify the terms of any separate license agreement you may have executed with Licensor regarding such Contributions. 6. Trademarks. This License does not grant permission to use the trade names, trademarks, service marks, or product names of the Licensor, except as required for reasonable and customary use in describing the origin of the Work and reproducing the content of the NOTICE file. 7. Disclaimer of Warranty. Unless required by applicable law or agreed to in writing, Licensor provides the Work (and each Contributor provides its Contributions) on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied, including, without limitation, any warranties or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE. You are solely responsible for determining the appropriateness of using or redistributing the Work and assume any risks associated with Your exercise of permissions under this License. 8. Limitation of Liability. In no event and under no legal theory, whether in tort (including negligence), contract, or otherwise, unless required by applicable law (such as deliberate and grossly negligent acts) or agreed to in writing, shall any Contributor be liable to You for damages, including any direct, indirect, special, incidental, or consequential damages of any character arising as a result of this License or out of the use or inability to use the Work (including but not limited to damages for loss of goodwill, work stoppage, computer failure or malfunction, or any and all other commercial damages or losses), even if such Contributor has been advised of the possibility of such damages. 9. Accepting Warranty or Additional Liability. While redistributing the Work or Derivative Works thereof, You may choose to offer, and charge a fee for, acceptance of support, warranty, indemnity, or other liability obligations and/or rights consistent with this License. However, in accepting such obligations, You may act only on Your own behalf and on Your sole responsibility, not on behalf of any other Contributor, and only if You agree to indemnify, defend, and hold each Contributor harmless for any liability incurred by, or claims asserted against, such Contributor by reason of your accepting any such warranty or additional liability. END OF TERMS AND CONDITIONS APPENDIX: How to apply the Apache License to your work. To apply the Apache License to your work, attach the following boilerplate notice, with the fields enclosed by brackets "[]" replaced with your own identifying information. (Don't include the brackets!) The text should be enclosed in the appropriate comment syntax for the file format. We also recommend that a file or class name and description of purpose be included on the same "printed page" as the copyright notice for easier identification within third-party archives. Copyright [yyyy] [name of copyright owner] Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.