- Description
- Setup - The basics of getting started with wsusserver
- Usage - Configuration options and additional functionality
- Reference - An under-the-hood peek at what the module is doing and how
- Development - Guide for contributing to the module
The wsusserver module installs, configures, and manages Windows Server Update Services (WSUS) on Windows systems.
Windows Server Update Services (WSUS) allows for administrators to manage the deployment of updates for products (SQL Server, Window Server 2016..etc) released by Microsoft.
The wsusserver module requires the following:
- Puppet Agent 4.7.1 or later.
- Windows Server 2016.
Note - The module also works on Windows Server 2012 & 2012 R2 with WMF(PowerShell) 5.1 installed, but only limited testing has been performed.
To get started with the wsusserver module simply include the following in your manifest:
class { 'wsusserver':
package_ensure => 'present',
update_languages => ['en'],
products => [
'Active Directory Rights Management Services Client 2.0',
'ASP.NET Web Frameworks',
'Microsoft SQL Server 2012',
'SQL Server Feature Pack',
'SQL Server 2012 Product Updates for Setup',
'Windows Server 2016',
],
update_classifications => [
'Critical Updates',
'Security Updates',
'Updates',
],
}This example installs, configures, and manages the wsusserver service. After running this you should be able to access the WSUS Console to begin you enterprise management of updates.
A more advanced configuration including most attributes available for the base/main class:
class { 'wsusserver':
package_ensure => 'present',
include_management_console => true,
service_manage => true,
service_ensure => 'running',
service_enable => true,
wsus_directory => 'C:\\WSUS',
join_improvement_program => false,
sync_from_microsoft_update => true,
update_languages => ['en'],
products => [
'Active Directory Rights Management Services Client 2.0',
'ASP.NET Web Frameworks',
'Microsoft SQL Server 2012',
'SQL Server Feature Pack',
'SQL Server 2012 Product Updates for Setup',
'Windows Server 2016',
],
product_families => [
'SQL Server',
'System Center',
],
update_classifications => [
'Critical Updates',
'Security Updates',
'Updates',
],
targeting_mode => 'Client',
host_binaries_on_microsoft_update => false,
synchronize_automatically => true,
synchronize_time_of_day => '03:00:00', # 3AM ( UTC ) 24H Clock
number_of_synchronizations_per_day => 1,
}The above is just an example of the flexibility you have with this module. You will generally never need to specify every or even so many parameters as shown.
Updates can be downloaded locally on the wsusserver and machines can pull approved and appropriate updates for installation straight from the wsusserver. Since updates from microsoft are very large in size this requires a good amount of disk space to be available. One option is to use the wsus server for approval and checking of updates and inform the clients they should pull updates directly from microsoft's updates servers relieving your server of the load and disk space. This can be configured like so.
class { 'wsusserver':
package_ensure => 'present',
host_binaries_on_microsoft_update => true,
}NOTE: In order to use this option each machine needs someway to get out to the public internet to pull their updates directly from microsoft.
Updates can be targeted in 2 ways. Client-side or Server-side. Server-side targeting indicates some administrator must move computers in the appropriate computer groups in order for them to get their desired updates. By default all computers that need to be manually classified will be found in the UnAssigned Computers group. Server-side target is rarely used since it requires manual intervention. While not recommended this can be done like so:
class { 'wsusserver':
package_ensure => 'present',
targeting_mode => 'Server',
}Typically Client-Side targeting is used which is why it's ths default in this module if not specified. Below is an example of setting client-side targeting explicitly.
class { 'wsusserver':
package_ensure => 'present',
targeting_mode => 'Client',
}This is typically done through 1 of 2 ways.
- Group-Policy
- Registry
It's recommended to avoid group policy all together and simply utilize the puppetlabs/wsus_client module ( which is a supported module by puppetlabs ) which handles configuring clients for client-side targeting.
The process of wsus server checking for new categories, products, and updates is called synchronization. While this can be done manually, it's typically done automatically on a configured scheduled. Below is an example of how to configure automatic synchronization every day at around 3:00AM UTC ( which is the default configured by this module ).
class { 'wsusserver':
package_ensure => 'present',
synchronize_automatically => true,
synchronize_time_of_day => '03:00:00', # 3AM ( UTC ) 24H Clock
number_of_synchronizations_per_day => 1,
}If you want four synchronizations a day starting at 3:00AM UTC your schedule would look like below and be configured as such.
| Number | Time To Sync |
|---|---|
| 1 | 3:00AM UTC |
| 2 | 9:00AM UTC |
| 3 | 3:00PM UTC |
| 4 | 9:00PM UTC |
class { 'wsusserver':
package_ensure => 'present',
synchronize_automatically => true,
synchronize_time_of_day => '03:00:00', # 3AM ( UTC ) 24H Clock
number_of_synchronizations_per_day => 4,
}NOTE: The synchronization time of day has a random offset up to 30 minutes from the what you specify. This is done automatically by microsoft in order to prevent a stampeeding herd on their servers.
You typically don't want WSUS to manage updates in all languages or even for all products, there is just too many and this would require a huge server just to pull this load. Therefore, you typically specify a subset of the full list of languages and products you would like wsus server to manage updates for. Below is an example of this.
class { 'wsusserver':
package_ensure => 'present',
update_languages => ['en'],
products => [
'Active Directory Rights Management Services Client 2.0',
'ASP.NET Web Frameworks',
'Microsoft SQL Server 2012',
'SQL Server Feature Pack',
'SQL Server 2012 Product Updates for Setup',
'Windows Server 2016',
],
product_families => [
'SQL Server',
'System Center',
],
update_classifications => [
'Critical Updates',
'Security Updates',
'Updates',
],
}NOTE: The list of products, classifications, and languages for microsoft is constantly changing and currently i'm unable to find an updated list of where these can be found. The best solution at the moment is to open wsusserver, Go to Options => Products and Classifications and picking a name of the product based on the tree view shown.
To configure sync and/or status report email notifications the smtp_hostname and smtp_sender_emailaddress must be configured
class { 'wsusserver':
....
# Update synchronized email notification settings
send_sync_notification => true,
sync_notification_recipients => ['notifications@mydomain.com', 'another@mydomain.com'],
#Status report email notification settings
send_status_notification => true,
status_notification_recipients => ['notifications@mydomain.com'],
notification_frequency => 'Weekly', # 'Weekly' or 'Daily'
notification_time_of_day => '03:00:00', # 3AM ( UTC ) 24H Clock
#SMTP Server Settings
smtp_hostname => 'smtp.mydomain.com',
smtp_sender_displayname => 'WSUS Server Notifications',
smtp_sender_emailaddress => 'wsusserver@mydomain.com',
##Optional settings
smtp_port => 25,
##Not yet implemented settings
smtp_requires_authentication => false,
smtp_username => '',
smtp_password => '',
}Typically you group servers into groups so that you can role out changes in a controlled fashion or in a certain way. Below shows how to create computer target groups in order to do this.
wsusserver_computer_target_group { ['Development', 'Staging', 'Production']:
ensure => 'present',
}Removing is just as simple as creating is.
wsusserver_computer_target_group { ['Development', 'Staging', 'Production']:
ensure => 'absent',
}NOTE: By Default, wsuserver has 2 built-in computer groups created. They are named 'All Computers' and 'Unassigned Computers'. The wsusserver base/main class declares these for you and therefore you don't need to create these in order to have these resources show up in your puppet reports as being present. Also because these built-in groups cannot be deleted, since wsusserver will not allow it, if you plan on doing any sort of purging of unmanaged computer target groups just make sure the main class is in the catalog so the purging will not fail trying to delete the above 2 built-in computer target groups.
When you initially install wsus ( and possibly in the future ) you might want to remove certain approval rules. Below shows how to remove the built in approval rule.
wsusserver::approvalrule { 'Default Automatic Approval Rule':
ensure => 'absent'
}Approving updates that you will always want/need can be a waste of time. Automatic approval rules can be created in order to help remove this burden. Below we automatically approval all Windows Server 2016 Security and Critical updates that apply to our servers in our production environment.
wsusserver::approvalrule { 'Automatic Approval for Security and Critical Updates Rule':
ensure => 'present',
enabled => true,
classifications => ['Security Updates', 'Critical Updates'],
products => ['Windows Server 2016'],
computer_groups => ['Production'],
}When you initially install wsus ( and possibly in the future ) you might want to remove certain approval rules. Below shows how to remove the built in approval rule.
wsusserver::approvalrule { 'Default Automatic Approval Rule':
ensure => 'absent'
}Parameters are optional unless otherwise noted.
Installs Windows Server Update Services (WSUS) and manages the configuration, service, and management tools.
Specifies whether the Windows Server Update Services (WSUS) role should be present. Valid options: 'present' and 'absent'.
Default: 'present'.
Specified if the management console should be installed. This is the GUI used to manage wsus.
Default: true.
Specifies whether or not to manage the desired state of the WSUS windows service.
Default: true.
Specifies whether the WSUS windows service should be running or stopped. Valid options: 'stopped' and 'running'.
Default: 'running'.
Whether or not the WSUS windows service should be enabled at boot, disabled, or must be manually started. Valid options: true, false, and 'manual'
Default: true.
Specifies the absolute path on the target system to store downloaded updates.
Default: 'C:\WSUS'.
Allows microsoft to collect statistics about your system configuration, events, and configuration of wsus to help microsoft improve the quality, reliability and performance of the product. Valid options: true, false
Default: true.
Specifices that this server should perform synchronizations against microsoft upate servers. This assumes this wsus server is an upstream wsus server in your environment. Valid options: true, false
Default: true.
The name of the upstream wsus server in your environment in which to synchronize this wsus server against.
Default: undef.
The port of the upstream wsus server in your environment in which to synchronize this wsus server against.
Default: 80.
Specifies if the upstream wsus server in your environment in which to synchronize this wsus server against is using SSL. Valid options: true, false
Default: false.
Required.
The languages in which you want updates for.
NOTE: This is required because this is specific to your organization's requirements.
Must supply either products or product_families
The specific products (e.g. Windows Server 2008 R2, Windows Server 2016), that you want WSUS to sync updates for.
Product families contain one or many products and are shown as groups in the product selection dialgue of the WSUS UI. Products are the individual products in these lists.
Specify '*' (i.e. a single string, rather than an array of strings) to synchronize all products in the WSUS inventory.
One way to get a complete list of products and product families is to run the following PowerShell command on a WSUS server:
(Get-WsusServer).GetUpdateCategories() | Sort-Object -Property Title, Type | Format-Table -Property Title, TypeBoth products and product_families may be supplied, as long as products does not equal '*' (all products).
NOTE: products or product_families are required because this is specific to your organization's requirements.
Must supply either products or product_families
The specific products families (e.g. Windows, SQL Server), that you want WSUS to sync updates for.
Product families contain one or many products and are shown as groups in the product selection dialgue of the WSUS UI. Products are the individual products in these lists.
You cannot provide this parameter if products is set to '*' (all products).
One way to get a complete list of products and product families is to run the following PowerShell command on a WSUS server:
(Get-WsusServer).GetUpdateCategories() | Sort-Object -Property Title, Type | Format-Table -Property Title, TypeBoth products and product_families may be supplied, as long as products does not equal '*' (all products).
NOTE: products or product_families are required because this is specific to your organization's requirements.
Required.
The classifications in which you want updates for.
NOTE: This is required because this is specific to your organization's requirements.
Specifies wether or not server-side or client-side targeting is to be utilized. Valid options: 'Server' and 'Client'.
Default: 'Client'.
Whether or not computers should download updates directly from Microsoft. Valid options: true, false
Default: true.
Whether or not to perform synchronizations automatically. Valid options: true, false
Default: true.
At what time synchronizations should happen in UTC time.
Default: 03:00:00. (Midnight UTC)
The number of times to perform synchronizations spreadout throughout the day starting at the synchronize_time_of_day parameter.
Default: 1.
Specifies that an intial synchronization of wsus should happen immediately after installation. Valid options: true, false
Default: true.
NOTE: Be aware that this step could take hours to finish! This will not cause any issues with puppet but it might look like it's stalled. It's not so just wait patiently! If you are testing this module out for the first time you probably want to set this value to false.
NOTE: The time it takes to finish the initial synchronization depends on the languages, products, and update classifications that were selected. It also depends on your internete connection as well.
NOTE: When you perform post-installation configuration tasks in the wsus wizard, this is the part at the end that has a check box asking if you want to begin initial synchronization.
Specifies that notifications should be sent when new updates are synchronized. Valid options: true, false
Default: false
NOTE: if set to true you must also specify sync_notification_recipient(s) and smtp server details
Specifies the recipients of sync notification emails. Accepts an arrays of addresses, e.g. ['notifications@mydomain.com', 'another@mydomain.com']
Default: ['']
Specifies that status reports. should be sent. Valid options: true, false
Default: false
NOTE: if set to true you must also specify status_notification_recipient(s) and smtp server details
Specifies the recipients of status notification (reports) emails. Accepts an arrays of addresses, e.g. ['notifications@mydomain.com', 'another@mydomain.com']
Default: ['']
Specifies frequency of status report notifications. Valid options: Weekly, Daily (note case)
Default: Weekly
Specifies time of day of status report notifications. In UTC time.
Default: '03:00:00', # 3AM ( UTC ) 24H Clock
Specifies the hostname of the smtp server. Example: 'smtp.mydomain.com'
Default: '' Required if notifications enabled
Specifies the display name of the sender of the notification email. Valid options: text string
Default: ''
Specifies the email address of the sender of the notification email. Valid options: Email Address. Example: 'wsusserver@mydomain.com' Required if notifications enabled
Specifies the port the smtp server accepts SMTP messages on. Valid options: integer number
Default: 25
Functionality not yet implemented
Specifies that the SMTP server requires anthenticiation to send messages. Valid options: true, false
Default: false
Functionality not yet implemented
Specifies username to use for SMTP server authentication
Default: ''
Required if smtp_requires_authentication is true
Functionality not yet implemented
Specifies password to use for SMTP server authentication
Default: ''
Required if smtp_requires_authentication is true
Parameters are optional unless otherwise noted.
Installs, configures, and manages WSUS computer target groups.
Specifies a computer target group to manage. Valid options: a string containing the name of your computer target group.
Default: the title of your declared resource.
Specifies whether the computer target group should be present. Valid options: 'present' and 'absent'.
Default: 'present'.
Parameters are optional unless otherwise noted.
Installs, configures, and manages WSUS Approval Rules.
Specifies a approval rule to manage. Valid options: a string containing the name of your approval rule.
Default: the title of your declared resource.
Specifies whether the approval rule should be present. Valid options: 'present' and 'absent'.
Default: 'present'.
Specifies whether the approval rule should be enabled. Valid options: true and false.
Default: true.
Required.
Specifies which computer groups this approval rule should apply to.
Required.
Specifies which products this approval rule should apply to.
Required.
Specifies which classifications this approval rule should apply to.
- Fork it ( https://github.com/tragiccode/tragiccode-wsusserver/fork )
- Create your feature branch (
git checkout -b my-new-feature) - Commit your changes (
git commit -am 'Add some feature') - Push to the branch (
git push origin my-new-feature) - Create a new Pull Request