How WPKG works?

From WPKG | Open Source Software Deployment and Distribution
Jump to: navigation, search

This document in other languages: French Spanish


WPKG is a script-driven installation engine for applications. Its main logic is contained within the wpkg.js file which is to be run on each client in a privileged user context. It can run a number of checks (i.e. check against file versions, file existence, uninstall entries, registry entries or the return value of an arbitrary command) and trigger arbitrary installation commands depending on the result.

It allows you to build dependency trees of applications and keeps an own package database for each client in order to be able to be smart about changed package definitions and package removals. Evaluating this information will allow you to stay informed about the installation progress for your clients.


WPKG configuration is kept in four separate files or is read from included subdirectories. The files define configuration options in structured XML syntax and can be changed easily in any text editor. You may even choose to generate some of them automatically.

These configuration files are:

  • hosts.xml - defines the hosts and associated profiles, which these hosts will use,
  • profiles.xml - defines the software packages or scripts, which will be installed/executed on hosts,
  • packages.xml - defines how to install and uninstall software packages. In other words, it is a list of all applications and scripts that can be deployed or executed on workstations.
  • config.xml - global WPKG configuration options

The main configuration files and the JScript "engine" (wpkg.js) need to be located in the same directory. In order to keep definitions for hosts, profiles and packages better organised in larger environments, they may be distributed among several *.xml files in subdirectories named "hosts", "profiles" and "packages".

Server software (Samba or Windows file server)

The only thing you really need on the server side when using WPKG is the file service. Basically, a share is needed which is accessible by all workstations and accomodates wpkg.js and the configuration files. Furthermore, you probably would want to have some share for your program installation sources (copies of the installation media for your software) and might consider having some network-accessible directory to store copies of the client-local package databases and WPKG log files to facilitate later evaluation of installation progress and the collection of errors. Actually, since Windows natively supports WebDAV on from Windows XP, you are not limited to SMB, but can use WebDAV servers as well.

Note: Make sure that your server is not providing any SMB-based services (eg, DC, shared printer or shared folder other than the one used by WPKG) to the client computer, otherwise you will face the infamous error at random times: Multiple connections to a server or shared resource by the same user. If it has to provide such services, you may use a DNS CNAME or IP address to refer to the server in the WPKG Client.

Client software (Windows workstations)

WPKG on the client side is just an executed JScript file - it needs no further software to run as such, although your software installers might require additional components (like Windows Installer 3.0). There are plenty of ways how you might run WPKG - take a look at Installation instructions - advanced for some ideas of how it can be done. However, the WPKG Client, a client-based service, should be appropriate for most basic needs. The basic idea behind all approaches is a command like this is executed on the client machine at some convenient point in time (typically at startup):

cscript \\server\wpkg\wpkg.js /synchronize /quiet

When WPKG is called on a Windows workstation with these options, it will do the following:

  • look for its hostname in \\server\wpkg\hosts.xml file, and a profile associated to the name,
  • look which software/scripts it has in a profile in \\server\wpkg\profiles.xml file,
  • look for detailed package descriptions in \\server\wpkg\packages.xml file - name, description, install command, remove command, exit code etc.

/synchronize means that WPKG will try to sync the packages - that is, install software if it's not already installed, execute scripts, and if it's successful, write the "status" to C:\Windows\System32\wpkg.xml (so that software installation is not started again if it's already installed).

Of course, WPKG has many more options. See WPKG flags for details.

You will likely run it manually as a local or domain Administrator when you would be still testing WPKG
(just open a command line using menu Start -> Run -> cmd).

When you're done with testing and finally configure everything the way you like, you will want to run it automatically on each of your dozens or hundreds of workstations.
When WPKG is installed, it runs and installs software automatically in the background, whenever the workstation boots up, even when no one has logged on to that PC.

Missing functions

WPKG cannot do everything (yet). Among the things it does not do are the following:

Installation of the Operating System

WPKG comes into play after the O/S is installed and running. For everything before that use approaches like RIS/WDS or Unattended for automated network-based installation of the O/S)

"Software push" functionality

WPKG is a client-centered approach to software installation, so it does not support "pushing" software. However, you are free to issue Remote Procedure Calls to clients in order to trigger the start of the WPKG service or even directly the start of the WPKG command

Software repackaging

WPKG is about scripted, unattended installations. In our experience, repackaged software while running fine most of the time, might cause obscure problems in rare cases and leaves the admin standing without any reasonable support from the software companies. This article at elaborates in a bit more detail on this matter.

Integrity or signature checking of installation packages

This is a security feature and while surely a valuable gain, nobody has yet been found to implement it.

Multicast deployments

Multicast transfers would be very valuable in narrow-bandwidth environments with shared media and a large number of clients - typically large wireless networks or networks connected through a narrow link (e.g. a 10 Mbps laser link). WPKG uses file services and installs software packages synchronously, using multicast would necessarily mean a different approach to file transfers and asynchronous installations. Anyway, a lot can be done using a local caching directory, a multicast transfer daemon like uftp and some intelligent scripting combined with WPKG.