b W W SSSSSSS U U SSSSSSS
b W W S U U S
b W W S U U S
b W W SSSSSSS U U SSSSSSS
v v bbbbbb W W W S U U S
v v b b W W W W S U U S
v v b b W W W W S S U U S S
v bbbbbb WW WW SSSSSSS UUUUUU SSSSSSS
YEAH SOME CRAZY ASCII ART :')
I. ABOUT vbWSUS
II. SETUP
III. PARAMETERS
IV. CSV FORMAT
V. CRON SYNTAX
VI. COMMAND LINE PARAMETERS
VII. SETUP EXAMPLES
VII.1 Active Directory configuration
VII.2 WSUS integration
Please report any bugs or suggestion via the contact
and website informations provided below.
--------------------------------------------------------
= I. ABOUT vbWSUS =
== I.1 Presentation ==
Author = snoopscratchy
Contact = snoopscratchy <at> gmail <dot> com (english or french)
Website = http://sourceforge.net/projects/vbwsus/
Support = https://sourceforge.net/p/vbwsus/tickets/
Mailing-lists = http://sourceforge.net/p/vbwsus/mailman/
Version = 1.9.0
Date = 2012/09/07
Prerequisites :
- ipc$ share must be accessible from your "vbWSUS server" (port 445)
- cscript.exe must be in your path
- remote hosts must respond to ping so vbWSUS can monitor
the reboot processus
this is only required if you set action to 'install_waitreboot'
or 'install_forcereboot'
RequiredFiles :
- conf\vbWSUS.conf : configure all vbWSUS parameters
- vbWSUS_scheduler.vbs : main script of vbWSUS,
checks the server schedules
if "Now" matches, starts the update processus
- vbWSUS_exec.vbs : handles the remote execution of
vbWSUS_SearchInstallDownload.vbs
using PSExec, fetching results
and sending notifications
- vbWSUS_SearchInstallDownload.vbs : runs remotely,
searches for updates and install them,
launch a reboot if required
- lib\common.inc : shared functions
required by vbWSUS_scheduler.vbs and vbWSUS_exec.vbs
- vbWSUS_admin.vbs : a command line tool to run the same things as vbWSUS_scheduler without schedule, check "cscript vbWSUS_admin.vbs help"
InputFile :
- a CSV file or an url serving a page formatted as a CSV,
see "III. SERVERLIST FORMAT" and "conf\serverlist.csv.sample"
RequiredFolders :
In order for vbWSUS to work properly, these folder need to be created
prior to schedule :
- logs\admin
- logs\exec
- logs\results
- logs\scheduler
I plan on adding the automatic creation of these folders but I m
(still still) lazy atm !
== I.2 Description ==
vbWSUS allows you to decide when to run Windows Update on a per host basis
- fill serverlist.csv with your desired schedules per host
- schedule a task in Task Manager to run
"cscript vbWSUS_scheduler.vbs" every minute
Moreover, vbWSUS_admin can help you remotely manage the updates on your servers :
- install updates
- hide/unhide updates
- reset SUS Id (useful for computers not showing up in WSUS console)
- add/remove/list schedules from serverlist.csv
== I.3 Logs & Reporting ==
=== I.3.a Logs ===
These are the default log files (relative to vbWSUS root):
- vbWSUS_admin.vbs logs to logs\admin\vbWSUS_admin.log
- vbWSUS_scheduler.vbs logs to logs\vbWSUS_scheduler.log
- vbWSUS_exec.vbs logs to logs\exec\vbWSUS.<hostname>.log
- vbWSUS_SearchInstallDownload.vbs logs to
1/ vbWSUS_SearchInstallDownload.log on the remote host
2/ logs\results\<hostname>.<timestamp>.log
(copied from vbWSUS_SearchInstallDownload.log
once vbWSUS_SearchInstallDownload.vbs has terminated)
=== I.3.b Reporting ===
You can configure vbWSUS to email you 3 types of information :
- whenever an error occurs
- when an update processus starts (when a schedule is triggered)
- when an update processus ends
All parameters can be found in vbWSUS.conf
== I.4 Debug ==
Each script comes with a "debug mode", just set "bDEBUG" to True
This will output more information prefixed by "DEBUG:"
Don't use debug mode in a production environment as the passwords
you may have provided will appear in clear text in the logs
--------------------------------------------------------
= II. SETUP =
1/ check for required folders and create them if missing, they should
normally be here as I include them in each release :
- logs\admin
- logs\exec
- logs\results
- logs\scheduler
2/ configure vbWSUS : open conf\vbWSUS.conf with your favorite text editor
and set the parameters as required (see III. Parameters).
the default configuration provides the following :
use conf\serverlist.csv as input source
install updates
matching "IsAssigned=1 and IsHidden=0 and IsInstalled=0
and Type='Software'"
matching "Critical,Important,Moderate"
don't modify the Windows Update Automatic Update configuration
don't configure a WSUS server
(if one is already configured on the remote host,
it will be used)
don't use a proxy server to connect to Windows Update or WSUS
(if one is already configured on the remote host,
it will be used)
reboot computer 5 minutes after the end of the installation
and monitor the reboot processus
don't send email notifications at all
3/ add some hosts to conf\serverlist.csv following the required syntax
4/ schedule vbWSUS_scheduler.vbs : within the Windows Task Scheduler,
create a new task to run every minute
(avoid running it every minute on the 59th second,
this would probably not trigger all schedules as expected !)
=> once a schedule matches the current YYYY/MM/DD HH:mm,
the required action is run against the specified host
--------------------------------------------------------
= III. PARAMETERS =
Parameters can be found in :
- conf\vbWSUS.conf
- conf\serverlist.csv
- vbWSUS_admin.vbs CLI
These parameters are :
schedule (cron), description, hostname, hostaddress, user, password,
action, proxy, server, config_au, scope, severity, title, script
There is a special parameter "script_action", see "III.1 script_action"
Some parameters accept values that cannot be guessed, here is the full
description for each parameter :
- where required
- synxtax/accepted values
- how to use it on CLI
- default value(s)
vbWSUS_admin doesn't use values defined in vbWSUS.conf
host parameters in serverlist will override parameters defined in vbWSUS.conf
== III.1 script_action ==
This is a special parameter that must be passed as the 1st argument when using
vbWSUS_admin.vbs
It tells vbWSUS_admin.vbs which action to perform.
Mandatory :
conf\vbWSUS.conf : N/A
conf\serverlist.csv : N/A
vbWSUS_admin.vbs CLI : mandatory
Syntax :
one of the following actions :
available for vbWSUS.conf and vbWSUS_admin :
install : install updates and reboot if required, don't monitor reboot
install_waitreboot : install updates, reboot if required and monitor reboot
install_noreboot : install updates but don't reboot, just notify
detect : detect available updates (matching scope/filter/title)
history : list all installed updates
available to vbWSUS_admin only :
config_proxy : only configure the proxy
config_server : only configure the WSUS server
config_au : only configure Automatic Updates
given the values defined in vbWSUS.conf
susid : reset SUS Id and force a report to the WSUS server,
useful for computer not showing up in WSUS console
hide/unhide : requires an extra parameter title="<string>",
hide or unhide updates matching <string>
CLI :
vbWSUS_admin.vbs install[_waitreboot|_noreboot] hostaddress=<hostaddress> [parameters]
vbWSUS_admin.vbs config_proxy hostaddress=<hostaddress> [proxy=<proxyURL>]
vbWSUS_admin.vbs config_server hostaddress=<hostaddress> [server=<WSUSserverURL>]
vbWSUS_admin.vbs config_au hostaddress=<hostaddress>
vbWSUS_admin.vbs susid hostaddress=<hostaddress>
vbWSUS_admin.vbs hide hostaddress=<hostaddress> title="<string>"
vbWSUS_admin.vbs unhide hostaddress=<hostaddress> title="<string>"
vbWSUS_admin.vbs history hostaddress=<hostaddress>
Default value :
none
== III.2 schedule (cron) ==
Mandatory :
conf\vbWSUS.conf : N/A
vbWSUS_admin.vbs CLI : required for "add"
conf\serverlist.csv : mandatory
Syntax :
see V. CRON SYNTAX
CLI :
vbWSUS_admin.vbs add schedule="<schedule>" hostaddress=<hostaddress> [parameters]
Default value :
none
== III.2 description ==
Mandatory :
conf\vbWSUS.conf : N/A
vbWSUS_admin.vbs CLI : optional
conf\serverlist.csv : optional
Syntax :
anything but the ";" char
CLI :
vbWSUS_admin.vbs add schedule="<schedule>" hostaddress=<hostaddress> [description="<description>" [parameters]]
Default value :
empty
== III.3 hostname ==
Mandatory :
conf\vbWSUS.conf : N/A
vbWSUS_admin.vbs CLI : optional, mandatory if "script_action" is "add"
conf\serverlist.csv : mandatory
Syntax :
anything accepted in a Windows Hostname
CLI :
vbWSUS_admin.vbs add schedule="<schedule>" hostaddress=<hostaddress> [hostname=<hostname> [parameters]]
Default value :
defaults to hostaddress if available, else none
== III.4 hostaddress ==
Mandatory :
conf\vbWSUS.conf : N/A
vbWSUS_admin.vbs CLI : mandatory
conf\serverlist.csv : mandatory
Syntax :
IP Address
anything accepted in a Windows Hostname
CLI :
vbWSUS_admin.vbs <script_action> hostaddress=<hostaddress> [parameters]
Default value :
none
== III.5 user & password ==
Mandatory :
conf\vbWSUS.conf : optional (strPSExecUsername, strPSExecPassword)
vbWSUS_admin.vbs CLI : optional
conf\serverlist.csv : optional
Syntax :
anything but the ";" char
CLI :
vbWSUS_admin.vbs <script_action> hostaddress=<hostaddress> [user=<user> password=<password [parameters]]
Default value :
current user
== III.6 proxy ==
Mandatory :
conf\vbWSUS.conf : optional (strWUProxyURL)
vbWSUS_admin.vbs CLI : optional
conf\serverlist.csv : optional
Syntax :
URL
ie: http://myproxy.mydomain.local:3128
CLI :
vbWSUS_admin.vbs <script_action> hostaddress=<hostaddress> [proxy=<proxy> [parameters]]
Default value :
empty
== III.7 server ==
Mandatory :
conf\vbWSUS.conf : optional (strWUServerURL)
vbWSUS_admin.vbs CLI : optional
conf\serverlist.csv : optional
Syntax :
URL
ie: http://mywsus.mydomain.local
CLI :
vbWSUS_admin.vbs <script_action> hostaddress=<hostaddress> [server=<server> [parameters]]
Default value :
empty
== III.8 config_au ==
Mandatory :
conf\vbWSUS.conf : optional (strWUConfigAUyn)
vbWSUS_admin.vbs CLI : optional
conf\serverlist.csv : optional
Syntax :
yes/no
CLI :
vbWSUS_admin.vbs <script_action> hostaddress=<hostaddress> [config_au=yes [parameters]]
Default value :
no
== III.9 scope ==
Mandatory :
conf\vbWSUS.conf : optional (strWUScope)
vbWSUS_admin.vbs CLI : optional
conf\serverlist.csv : optional
Syntax :
string accepted by the updateSearcher.Search() function
a combination of some or all of the following keywords :
IsAssigned=0|1
IsHidden=0|1
IsInstalled=0|1
Type='Software'|'Driver'
linked by "And" or "Or" ("Or" needs to be confirmed, never tried it)
ie : "IsAssigned=1 and IsHidden=0 and IsInstalled=0 and Type='Software'"
"IsInstalled=0 and Type='Software'"
CLI :
vbWSUS_admin.vbs <script_action> hostaddress=<hostaddress> scope="IsInstalled=0 and Type='Software'" [parameters]
Default value :
"IsAssigned=1 and IsHidden=0 and IsInstalled=0 and Type='Software'"
== III.10 severity ==
severity="<string>"
<string> : a list of comma separated severities in the following list
Critical,Important,Moderate,Low,NoSeverity,_ALL_,_TITLE_ONLY_
Will include updates whose severity rating matches with specified severities
filter="Critical,Important" will include updates
whose severity is "Critical" or "Important"
Mandatory :
conf\vbWSUS.conf : optional (strWUSeverity)
vbWSUS_admin.vbs CLI : optional
conf\serverlist.csv : optional
Syntax :
a comma separated string, no ";" accepted
all severities : "Critical,Important,Moderate,Low,NoSeverity", same as "_ALL_"
Critical or Important : "Critical,Important"
Don't use severities at all (rely only on title search) : "_TITLE_ONLY_"
CLI :
vbWSUS_admin.vbs <script_action> hostaddress=<hostaddress> filter="Critical,Important" [parameters]
Default value :
if title|strWUTitle = "", filter|strWUSeverity = "_ALL_"
if title|strWUTitle <> "", filter|strWUSeverity = "_TITLE_ONLY_"
== III.11 title ==
title="<string>"
<string> : a list of comma separated strings
Will include updates whose title matches with specified strings
title can be additive with "III.11 filter"
. filter="Critical,Important" and title="Internet Explorer" will include updates
whose severity is "Critical" or "Important" and will also include updates whose
. title matches "Internet Explorer" regardless of their severity classification
filter="" and title="Internet Explorer" will ONLY include updates
whose title matches "Internet Explorer"
Mandatory :
conf\vbWSUS.conf : optional (strWUTitle)
vbWSUS_admin.vbs CLI : optional
conf\serverlist.csv : optional (linked to "filter", see syntax below)
Syntax :
a comma separated string, no ";" accepted
To include updates matching "Internet Explorer" or "Service Pack" : "Internet Explorer,Service Pack"
/!\ in serverlist.csv, appended by "|" to the filter parameter
ie : "Critical,Important|Internet Explorer,Service Pack"
CLI :
vbWSUS_admin.vbs <script_action> hostaddress=<hostaddress> title="Internet Explorer,Service Pack,Definition Update for Windows Defender" [parameters]
Default value :
empty = just match updates by severity (filter)
== III.12 script ==
Mandatory :
conf\vbWSUS.conf : optional (strPSExecScript)
vbWSUS_admin.vbs CLI : optional
conf\serverlist.csv : optional
Syntax :
any valid path
CLI :
vbWSUS_admin.vbs <script_action> hostaddress=<hostaddress> [script=<path> [parameters]]
Default value :
C:\admin\vbWSUS\vbWSUS_SearchInstallDownload.vbs
--------------------------------------------------------
= IV. CSV FORMAT =
Note: All these parameters can be configured inside vbWSUS.conf
so you don't have to fill each line with the same parameters
BUT you can override default parameters configured in vbWSUS.conf
by setting them in the CSV file
Example: If strPSExecUsername and strPSExecPassword are set to ""
in vbWSUS.conf, you can specify a custom login/password
for a certain host here.
This behaviour is valid for all parameters listed below.
If you leave a column empty, the value configured in vbWSUS.conf
will be used
(or the command line argument passed to vbWSUS_scheduler.vbs)
There are 13 columns with the following names :
1 2 3 4 5 6 7
schedule ; description ; hostname ; hostaddress ; user ; password ; action ;
8 9 10 11 12 13
proxy ; server ; config_au ; scope ; filter ; script
[mandatory] schedule : see III. CRON SYNTAX
[optional] description : any desription you want to give,
DO NOT USE ";" characters,
empty = no description
[mandatory] hostname : the display name of the host
[mandatory] hostaddress : the IP or resolvable FQDN to the host
[optional] user : the account used to connect to the remote host,
empty = vbWSUS.conf::strPSExecUsername
[optional] password : password associated to the specified user,
empty = vbWSUS.conf::strPSExecPassword
[optional] action : Windows Update action to run on remote host,
empty = vbWSUS.conf::strWUAction
[optional] proxy : proxy server to use to reach
the Windows Update server,
empty = vbWSUS.conf::strWUProxyURL
[optional] server : WSUS server to use,
empty = vbWSUS.conf::strWUServerURL
[optional] config_au : yes = configure Windows Update AutomaticUpdates,
empty = vbWSUS.conf::strWUConfigAUyn
[optional] scope : detect Windows Update matching scope,
empty = vbWSUS.conf::strWUScope
[optional] filter : filter available updates by severity
and/or title
empty = vbWSUS.conf::strWUSeverity
| vbWSUS.conf::strWUTitle
[optional] script : specify the full _local_ path where the script
should be copied on remote host,
empty = vbWSUS.conf::strPSExecScript
/!\ Although many parameters are optionnal, their position still need to be
in the same order as above and separated by ";"
/!\ Trailing optional parameters ";" separator can be omitted
if they are not set
ie : "0 2 L * *;Empty args example, no trailing semicolon;PC;127.0.0.1;PC\administrator;password;;http://my.wsus-server.lan"
=> the config_au, search, filter, script parameters are omitted
--------------------------------------------------------
= V. CRON SYNTAX =
== V.1 Recurring schedule ==
Cron syntax (from http://en.wikipedia.org/wiki/Crontab)
* * * * * command to be executed
- - - - -
¦ ¦ ¦ ¦ ¦
¦ ¦ ¦ ¦ ¦
¦ ¦ ¦ ¦ +----- day of week [0-6] (0 is Sunday), * = everyday
¦ ¦ ¦ ¦ optional suffixes : #[1-4] or L
¦ ¦ ¦ ¦ #[1-4] : run on week number "#"
¦ ¦ ¦ ¦ 3#2 = run on second wednesday
¦ ¦ ¦ ¦ L : run on last occurence of specified day
¦ ¦ ¦ ¦ 5L = run last friday
¦ ¦ ¦ ¦
¦ ¦ ¦ +---------- month [1-12], * = current month
¦ ¦ ¦
¦ ¦ +--------------- day of month [1-31L]), * = everyday
¦ ¦ if set to L, run on last day of month
¦ ¦
¦ +-------------------- hour [0-23], * = 0
¦
+------------------------- min [0-59], * = 0
Examples :
0 0 * * * : Every day at midnight
30 1 * * 0 : Every sunday at 1:30 AM
10 14 * * 6 : Every saturday at 2:10 PM
0 1 * * 6#3 : Every 3rd saturday of every month at 1:00 AM
0 3 * * 4L : Every last thursday of every month at 3:00 AM
0 2 20 * * : Every 20th of every month at 2:00 AM
0 2 L * * : Last day of every month at 2:00 AM
== V.2 One time schedule ==
In order to run a schedule only once on a specified date,
you can set the cron value to the following date format : YYYY/MM/DD HH:mm
Examples :
2012/12/12 00:00 : Run at midnight on the 12th of December in year 2012
--------------------------------------------------------
= VI. COMMAND LINE PARAMETERS =
vbWSUS_admin.vbs have a CLI.
You can get help by calling the script with the "help" parameter.
vbWSUS_admin.vbs help
== VI.1 vbWSUS_admin.vbs ==
/!\ parameters not specified on the commandline will use default configured
in conf\vbWSUS.conf
Syntax is as follow :
vbWSUS_admin.vbs <action> <parameters> [parameters]
With :
<> = required, [] = optional
parameters = a list of space separated parameters
ie 'param1=val1 param2=val2 ...'
valN can contain space(s) as long as you surround it with quotes
vbWSUS_admin.vbs add schedule="<schedule>" hostname=<hostname> hostaddress=<hos
taddress> [parameters]
=> add a new schedule
vbWSUS_admin.vbs list [parameters]
=> list all schedules or schedules matching [parameters]
vbWSUS_admin.vbs enable|disable <parameters>
=> enable/disable schedule(s) matching <parameters>
vbWSUS_admin.vbs <action> hostaddress=<hostaddress> [parameters]
=> run <action> on <hostaddress> with [parameters]
Available actions :
install
install_waitreboot
install_noreboot
detect
filter
config_proxy
config_server
config_au
susid
hide/unhide <title=matching string>
Available parameters :
source = where to find the server list
user = which account to use for remote connections
password = password associated with username
search = the Windows Update search scope
(' and ' and ' or ' may be replaced by '&' and '|')
filter = the filter to apply once the search is done
(ie: Critical,Important)
title = the string to find in the update title
config_au = apply or not the Windows Update Automatic Updates
registry configuration defined in conf\vbWSUS.conf
server = which WSUS server to use
proxy = which proxy to use
script = where to copy and execute vbWSUS_SearchInstallDownload.vbs
on the remote host
Only for action=hide/unhide :
title = string to match in order to hide/unhide update(s)
multiple strings can be specified, separated by a comma
--------------------------------------------------------
= VII. SETUP EXAMPLES =
== VII.1 Active Directory configuration ==
In an Active Directory domain, I'd recommend to use the same account to remotely log to every machine.
The easiest way then to setup vbWSUS is to use this account to schedule vbWSUS_scheduler.vbs in the Task Manager
You will not need to specify the username and password in the serverlist.csv file nor in the vbWSUS_scheduler.vbs
Your serverlist.csv file will then look like this :
<schedule>;<description>;<hostname>;<hostaddress>
Your vbWSUS.conf will look like this :
(...)
strPSExecUsername = "" ' empty = use credentials used to start the script to connect and run psexec on remote host
strPSExecPassword = "" ' not needed if strPSExecUsername is empty, else cannot be empty
(...)
If you have a computer out of the Active Directory domain, you can still add it to serverlist.csv and specify a custom login/password,
or any other option you need for this specific host, which means that your serverlist.csv may look like this :
# Domain servers
<schedule>;<description>;<hostname>;<hostaddress>
<schedule>;<description>;<hostname>;<hostaddress>
<schedule>;<description>;<hostname>;<hostaddress>
(...)
# DMZ servers
<schedule>;<description>;<hostname>;<hostaddress>;<username>;<password>;<specific_proxy_server>;<specific_wsus_server>
== VII.2 WSUS integration ==
In case you already have a WSUS server, I'd recommend the following configuration in vbWSUS.conf :
strWUAction = "Install" ' Value can be Install, Detect or Filtered
strWUScope = "IsAssigned=1 and IsHidden=0 and IsInstalled=0 and Type='Software'"
strWUSeverity = "_ALL_" ' => You want to get all updates that you approved on your WSUS server
strWUConfigAUyn = "no" ' => Let your GPO configure the Windows Update Automatic Updates behavior
(probably set it to "download and ask" but I can't confirm yet that
the downloaded updates are used by vbWSUS and that it doesn't trigger
another download)
strWUServerURL = "" ' => GPO or as needed
strWUProxyURL = "" ' => configure proxy as needed
Download Latest Version
vbWSUS_1_9_0.zip (247.4 kB)
