61
edits
Changes
Created page with 'Este documento en otros idiomas: English French ---- '''packages.xml''' es el fichero que indica como realizar las instalaciones, actual…'
Este documento en otros idiomas: [[Packages.xml|English]] [[Packages.xml:French|French]]
----
'''packages.xml''' es el fichero que indica como realizar las instalaciones, actualizaciones y desinstalaciones de los paquetes de software. En otras palabras, es la lista de todos los programas y scripts que pueden ser instalados o ejecutados en las estaciones de trabajo..
Este fichero se localiza en el mismo directorio que [[wpkg.js]].
[http://wpkg.org WPKG] no trabajará sin este fichero.
==packages.xml estructura==
La estructura básica de '''packages.xml''' es la siguiente:
<source lang="xml">
<packages>
<package
id="wpkg1"
name="Windows Packager sample 1"
revision="1"
reboot="false"
priority="0">
<check type="registry" condition="exists" path="HKLM\Software\wpkg\full\key\not\part\of\it" />
<check type="file" condition="exists" path="%PROGRAMFILES%\wpkg\wpkg.bat" />
<check type="uninstall" condition="exists" path="WPKG" />
<install cmd='msiexec /i (path to msi)'>
<exit code="0" />
</install>
<remove cmd='%PROGRAMFILES%\uninstall\uninst.exe -quiet' />
<upgrade cmd='msiexec /i (path to msi)' />
</package>
</packages>
</source>
Cada paquete tiene los siguientes atributos:
* '''id''' - un identificador único que representa al paquete. DeberÃa ser corto y representativo
* '''name''' - longer textual description of the package. This should be the full product name.
* '''revision''' - user created version number to represent the "version" of the specific WPKG package for this application. If you change the package, increment it. It can be the revision that the WPKG package is for, or the software application's version (though note such a strategy won't leave you room to change your WPKG package, for example when making an improvement or fixing a bug in the XML, other than when the software application is also upgraded).
** The following formats are supported:
*** an integer (1, 10, 1000, etc.)
*** dotted revision numbers (1.1, 2.1.4, 3.200.3987, etc.) ... introduced with WPKG 1.0
*** volatile revisions (1.2RC1, 1.5I32, 2.73M24, 1.65.b, etc.) ... introduced with WPKG 1.1.1 (see the changelog for more examples)
** If you like to keep track of the date you have last changed the package, because there is no better revision number, you can use the format YYYY.MM.DD (2010.07.27, etc.)
** In addition one can define a variable inside the package and use that as the revision, which is useful, if this is used in different places inside the package (package revision, path of installer, checks, etc.) ... introduced with WPKG 1.1.2:
<source lang="xml">
<package
id="firefox"
name="Mozilla Firefox"
revision="%PKG_VERSION%"
reboot="false"
priority="10">
<variable name="PKG_VERSION" value="3.6.8" />
</source>
* '''reboot''' - specifies if and how the system reboots when installing, removing or upgrading a given package.
** true - always reboot after processing this package.
** postponed - reboot after WPKG has finished processing all packages, if the package checks are successful after the action.
** anything else - do not cause a reboot because of this package. Other packages may still cause a reboot.
* '''priority''' - specifies a numeric value that determines in what order a package will be installed. The higher the number, the higher the priority, and so the earlier the package will be installed compared with lower priority packages. For example:
** 2 - installs these packages 1st
** 1 - installs these packages 2nd
** 0 - installs these packages 3rd
Note that a package installer with priority '5' would install before all these.
* '''execute''' ''(optional)'' - see [[Execute_once_/_always]]
== Check conditions / check type ==
Of course it would be unwise to launch the installer if the software is already installed. That's why there are "check conditions".
The check conditions are also used after the installer has finished to verify that the software has actually been successfully installed.
If no check statements exist in the package, WPKG will just run the install (or upgrade) commands and (as long as no error occurs) will add/update the package details in the local client database.
Check conditions are broken down into 4 categories:
*'''Registry''' - Checks the registry for conditions
*'''File''' - Verifies various information about files within the filesystem
*'''Uninstall''' - Checks the software installation registry key (as displayed in Windows' Add/Remove Programs section) for the existence of an existing package
*'''Execute''' - Executes a script and checks the returning errorlevel (since WPKG 1.1.0)
*'''Logical''' can also be used
===Registry===
Registry checks allow you to check for the existence of or a specific value in a registry key ('''Note''': for pre-1.0 versions,
it works on a registry value only, not a registry key!).
Beware, there is a limitation of the RegRead method used by WPKG's Registry checks to query registry values which contain backslashes ('\'). See the Execute section below to use instead to address this issue.
There are two possible conditions available for registry checks: ''exists'' and ''equals''.
<div style="margin-left: 30px">
'''exists''' - This checks for the existence of a registry key. If the registry key is found, the condition returns true, otherwise it returns false.
'''equals''' - This checks a specific value of a registry key. If the registry value is found and that value is equal to the supplied value, the condition returns true, otherwise it returns false.
</div>
Examples:
This checks for the existence of Adobe Reader within the registry:
<source lang="xml">
<check type="registry" condition="exists" path="HKLM\Software\Adobe\Adobe Reader\7.0" />
</source>
This checks to see if Firefox, US English, version 1.5.0.6, is installed:
<source lang="xml">
<check type="registry" condition="equals" path="HKLM\Software\Mozilla\Mozilla Firefox\CurrentVersion" value="1.5.0.6 (en-US)" />
</source>
===File===
File checks allow you to check for the existence of a file, check for a particular file's size, or examine version information about a file. There are several possible conditions available for file checks:
<div style="margin-left: 30px">
'''exists''' - This checks for the existence of a file. If the file is found, the condition returns true.
'''sizeequals''' - This checks the size of a file. If the file is found and the size equals the value supplied, the condition returns true.
'''versionsmallerthan''' - This checks the version of a particular file. If the file is found and the version is less than the supplied version number, the condition returns true.
'''versionlessorequal''' - This checks the version of a particular file. If the file is found and the version is less than or equal to the supplied version number, the condition returns true.
'''versionequalto''' - This checks the version of a particular file. If the file is found and the version is equal to the supplied version number, the condition returns true.
'''versiongreaterorequal''' - This checks the version of a particular file. If the file is found and the version is greater than or equal to the supplied version number, the condition returns true.
'''versiongreaterthan''' - This checks the version of a particular file. If the file is found and the version is greater than the supplied version number, the condition returns true.
</div>
Examples:
This checks for the existence of Adobe Reader within the filesystem:
<source lang="xml">
<check type="file" condition="exists" path="%PROGRAMFILES%\Adobe\Acrobat 7.0\Reader\AcroRd32.exe" />
</source>
This checks to see if Firefox US English version 1.5.0.6 is installed based on the file size of the executable:
<source lang="xml">
<check type="file" condition="sizeequals" path="%PROGRAMFILES%\Mozilla Firefox\firefox.exe" value="7183469" />
</source>
This checks whether the version of Firefox .exe that's currently installed is less than 1.5.0.6:
<source lang="xml">
<check type="file" condition="versionsmallerthan" path="%PROGRAMFILES%\Mozilla Firefox\firefox.exe" value="1.5.0.6" />
</source>
===Uninstall===
Uninstall checks allow you to check the Microsoft software installation registry keys (as displayed in Windows' Add/Remove Programs section) for the existence of a particular package. Microsoft maintains the list
of applications installed and available for uninstallation in the ''HKLM\Software\Microsoft\Windows\CurrentVersion\Uninstall'' registry key. The value in the DisplayName key of a particular package is what's matched by this check.
pre-1.1.0 versions of WPKG have only one condition available for this option: ''exists''.
<div style="margin-left: 30px">
'''exists''' - This checks for the existence of the particular software package in the installation database. If the package is found, the condition returns true.
</div>
Since version 1.1.0 this check is extended with several other conditions:
<div style="margin-left: 30px">
'''versionsmallerthan''' - This checks for the existence of a particular software package in the installation database and also checks the version of that software package. If the package is found, and the version is smaller than the supplied value, the condition returns true.
'''versionlessorequal''' - This checks for the existence of a particular software package in the installation database and also checks the version of that software package. If the package is found, and the version is less than or equal to the supplied value, the condition returns true.
'''versionequalto''' - This checks for the existence of a particular software package in the installation database and also checks the version of that software package. If the package is found, and the version is equal to the supplied value, the condition returns true.
'''versiongreaterorequal''' - This checks for the existence of a particular software package in the installation database and also checks the version of that software package. If the package is found, and the version is greater than or equal to the supplied value, the condition returns true.
'''versiongreaterthan''' - This checks for the existence of a particular software package in the installation database and also checks the version of that software package. If the package is found, and the version is greater than the supplied value, the condition returns true.
</div>
Examples:
This checks for the existence of Adobe Reader through the installation list:
<source lang="xml">
<check type="uninstall" condition="exists" path="Adobe Reader 7.0" />
</source>
This checks to see if Firefox version 1.5.0.6 is installed in the installation list:
<source lang="xml">
<check type="uninstall" condition="exists" path="Mozilla Firefox (1.5.0.6)" />
</source>
This checks for the existence of The Gimp 2.6.6 or higher through the installation list:
<source lang="xml">
<check type="uninstall" condition="versiongreaterorequal" path="GIMP" value="2.6.6" />
</source>
===Execute===
Execute allows you to execute any script which checks if an application is installed. WPKG checks the exit code of the script to determine the existence of the particular software package.
This type of check also allows very complex checks. For example there is a limitation of the RegRead method used by WPKG's Registry checks to query registry values which contain backslashes '\'. Now you can execute a batch script which checks for such registry values using 'reg query ...'.
There are several possible conditions available for execute checks:
<div style="margin-left: 30px">
'''exitcodesmallerthan''' - This checks the exit code of the executed script. If the exit code is smaller than the supplied value, the condition returns true.
'''exitcodelessorequal''' - This checks the exit code of the executed script. If the exit code is less or equal to the supplied value, the condition returns true.
'''exitcodeequalto''' - This checks the exit code of the executed script. If the exit code is equal to the supplied value, the condition returns true.
'''exitcodegreaterorequal''' - This checks the exit code of the executed script. If the exit code is greater than of equal to the supplied value, the condition returns true.
'''exitcodegreaterthan''' - This checks the exit code of the executed script. If the exit code is greater than the supplied value, the condition returns true.
</div>
Examples:
This evaluates true if the exit code is negative
<source lang="xml">
<check type="execute" path="\\path\to\script.cmd" condition="exitcodesmallerthan" value="0">
</source>
This evalueates true if exit code is 0 or negative
<source lang="xml">
<check type="execute" path="\\path\to\script.cmd" condition="exitcodelessorequal" value="0" >
</source>
This evaluates true only if exit code is exactly 0
<source lang="xml">
<check type="execute" path="\\path\to\script.cmd" condition="exitcodeequalto" value="0" >
</source>
This evaluates true if exit code is 0 or any positive number
<source lang="xml">
<check type="execute" path="\\path\to\script.cmd" condition="exitcodegreaterorequal" value="0" >
</source>
This evaluates true if exit code is any positive number
<source lang="xml">
<check type="execute" path="\\path\to\script.cmd" condition="exitcodegreaterthan" value="0" >
</source>
===Logical Conditions===
There can be zero or more conditions verified during the existence checks. If no conditions are supplied, WPKG attempts to install the package regardless of whether it's currently
installed or not. To facilitate using more than one condition, there is a 4th type of condition that can be added, called the logical condition. Logical conditions allow you to create
multiple conditions while checking for the presence of an existing package. Logical conditions are top level conditions, with the real check conditions as subnodes in the XML.
The following logical conditions are available: ''not'', ''and'', ''or'', ''atleast'', and ''atmost''.
*) both ''atleast'' and ''atmost'' do require the parameter ''value=''
Examples:
Let's say, for the sake of argument, that you have an Adobe Reader 7.0.8 package that you want installed, but you only want it installed on workstations
that are running Windows XP Service Pack 2 or higher, due to some strange incompatibility. Let's also say that some workstations can't be
upgraded to Windows XP Service Pack 2 until those workstations are upgraded from 256MB of memory to 512MB of memory. For a scenario like this, you could
(and probably should!) use multiple profiles and have those SP1 workstations in one profile, while the SP2 workstations are in another. However, just
for example purposes, let's say all workstations are in a single profile. You can provide a logical condition in order for only those workstations
running SP2 to be upgraded to Adobe Reader 7.0.8:
<source lang="xml">
<check type="logical" condition="or">
<check type="registry" condition="exists" path="HKEY_LOCAL_MACHINE\SOFTWARE\Adobe\Acrobat Reader\7.0\Installer\Updates\708" />
<check type="registry" condition="equals" path="HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows NT\CurrentVersion\CSDVersion" value="Service Pack 1" />
</check>
</source>
The 2nd condition here might seem counter intuitive, but remember that you're looking for the absence of things rather than the existence of things when you're writing
check conditions. What the above condition says is "Is Adobe Reader 7.0.8 installed or is Service Pack 1 installed? If either of these conditions equates to true,
the installation will be skipped. In this particular case, Adobe Reader 7.0.8 isn't installed, but the value of CSDVersion is Service Pack 1 (for the SP1 boxes)
so the software will not be installed.
Once all conditions have been tested, if the final result of the conditions is equal to false, WPKG will try to execute the "'''install cmd'''".
After it's executed, WPKG will check the exit code (should be 0 in this example) '''*and*''' verify all the checks.
If '''*any*''' of the checks are not met, software is considered '''*not*''' installed - so enter these values carefully!
Also, if no checks were specified, WPKG will say that the installation have failed. Although this is useful for cases where you want to install the package every time WPKG runs, you will probably want the installation without an error - see [[Execute once / always]] for executing packages without any checks.
Remember that you don't have to specify all three check conditions, usually one is enough: if the software you are about to install will show up in Windows' Add/Remove Programs (and not all do), it is sufficient to specify just the "'''uninstall'''" check.
==Actions==
WPKG understands several actions: '''install''', '''upgrade''', '''downgrade''', '''remove''' and '''download'''. Multiple commands for each of these actions can be listed in the config file and WPKG will execute them in the order they are listed.
The '''install''' commands are executed by WPKG when a new package comes into scope for a profile.
The '''upgrade''' commands are executed when a new revision of a package comes into scope. That is, when the '''revision''' number in the '''packages.xml''' file on the server is larger than the one in the local '''wpkg.xml''' file. Note that the upgrade commands will be run even if the check conditions are already met.
The '''downgrade''' commands are executed if the version installed on the client is newer than the one on the server side.
The '''remove''' commands are executed when a package is removed from a profile.
The '''download''' commands are always executed when used on the global package level. Since WPKG version 1.1.0 however, this command is also allowed as a sub-node of any of the other commands. This allows you to specify a download which is only downloaded for a specific command. This was implemented since it usually makes no sense to download the installation package again right before the remove commands are executed (which usually runs a local uninstall command which does not need the original installer). '''Note:''' If multiple install (or upgrade/downgrade/remove) commands are specified WPKG will download the the files of all command nodes of the same kind before starting to execute the commands in sequence.
In many of the examples in the [[:Category:Silent_Installers]] section, cmd.exe is executed to perform environment variable expansion and to use 'start /wait' to wait on the command being executed. This method of executing commands results in cmd windows appearing on screen. However, this method does not appear to be necessary. The current version of WPKG executes commands using the WScript.Shell.Exec() function and expands environment variables before execution. WPKG then waits until the command is completed before continuing.
The correct method of executing a command interpreter is to use the %comspec% environment variable, not specifying cmd.exe explicitly. This is needed to run commands that are built into the interpreter and are not separate executables.
When the output of a command (think of: copy,cacls) is too much, the command will fail. You have to redirect the output to NUL or a file (example: "%command% >nul").
Typical examples:
<source lang="xml">
<download url='http://wpkg.example.com/installers/some.msi' target="installers\some.msi" />
<install cmd="msiexec /qn /i %SOFTWARE%\package.msi" />
<install cmd="msiexec /qn /i %SOFTWARE%\package.msi" timeout="1800" />
<install cmd="%comspec% /c copy %SOFTWARE%\file.dll %WINDIR%" />
<remove cmd="msiexec /qn /x %SOFTWARE%\package.msi" />
</source>
The timeout option ([[Timeouts]]) tells WPKG how long to wait for the command to complete. It is in seconds and the default is 3600 seconds.
If the command you specify returns a value of "0" then wpkg assumes it was successful and continues with the next command, if any. If the command returns a nonzero value, then wpkg stops and logs a failure for the package. Sometimes nonzero exit codes are expected and you want to accept them. You can do this by adding exit code sections inside the install section, like this:
<source lang="xml">
<install cmd="msiexec /qn /i %SOFTWARE%\package.msi" >
<exit code="0" />
<exit code="259" />
</install>
</source>
If you don't care about exit code, use <code>exit code="any"</code>:
<source lang="xml">
<install cmd="msiexec /qn /i %SOFTWARE%\installer.exe /silent" >
<exit code="any" />
</install>
</source>
You can set a specific reboot action for certain exit codes with something like the following:
<source lang="xml">
<install cmd="msiexec /qn /i %SOFTWARE%\package.msi" >
<exit code="3010" reboot="true" />
<exit code="0" />
</install>
</source>
The options for the exit code reboot are:
* true - immediate reboot, without updating wpkg.xml
* delayed - reboot once the package action is complete and wpkg.xml is updated
* postponed - reboot once all the packages have been processed
Please note that the target value for a download action is always relative to the downloadDir defined in wpkg.js (and there's currently no configuration option to change this from the default of %TEMP%).
==Quick examples==
Other example - WPKG checks if the package is installed only in Windows' Add/Remove Programs before deciding to install it (to make sure it is not installed already):
<source lang="xml">
<package
id="wpkg3"
name="Windows Packager sample 3"
revision="1"
reboot="false"
priority="1">
<!--
This is a comment.
Checks in Windows' Add/Remove Programs only.
-->
<check type="uninstall" condition="exists" path="WPKG" />
<install cmd='%PACKAGES%\package.exe /quiet /install' />
<remove cmd='%PACKAGES%\package.exe /quiet /uninstall' />
<upgrade cmd='%PACKAGES%\package.exe /quiet /install' />
</package>
</source>
In the example below, there are no check conditions.
This means that WPKG will execute it each time - so this is rather useful for executing scripts that need to be run each time the machine is booted, than installing software:
<source lang="xml">
<package
id="backupfiles"
name="Makes backup of some file"
revision="1"
reboot="false"
priority="0">
<!--
This is a comment.
'''No check conditions; script will be executed *each time* wpkg.js is called - each time PC is booted.'''
-->
<install cmd='\\server\path\script.bat' />
</package>
</source>
Similar example, without any conditions, either.
Note the '''execute="once"''' entry - this means that that script will be executed only once. It is useful for the tasks you want
to do one time only, like disk defragmenting, some testing, changing printers etc.
<source lang="xml">
<package
id="backupfiles"
name="Makes backup of some file"
revision="1"
reboot="false"
execute="once"
priority="0">
<install cmd='\\server\path\script.bat' />
</package>
</source>
Similarly, you may want to execute a program or script each time - use "always" instead of "once". For more info on this functionality, check [[Execute_once_/_always|here]].
==Package dependencies==
Packages can also depend on other packages, see [[package dependencies]] for more info.
==Individual XML package files==
If you would rather keep your package XML description in separate files, you can of course do that: just create a <code>packages</code> directory where <code>wpkg.js</code> is, and place individual XML files there (i.e., thunderbird.xml, firefox.xml etc.). The syntax is the same as that of packages.xml.
Note, if you decide to keep all your packages in separate XML files, you still need a <code>packages.xml</code> file, which should at least contain an empty entry:
<source lang="xml">
<?xml version="1.0" encoding="UTF-8"?>
<packages>
</packages>
</source>
Here is an example of an individual XML file - note that it must contain <packages> at the beginning and </packages> at the end:
<source lang="xml">
<?xml version="1.0" encoding="UTF-8"?>
<packages>
<package id="setadminpassword"
name="Set admin password"
revision="1"
priority="999"
reboot="false"
execute="once">
<install cmd='cmd /c net user administrator password' />
</package>
</packages>
</source>
WARNING! Please note for this example: The password is visible in the local copy of wpkg.xml, so remove after installation, or better yet, use the command in a separate .bat file.
'''You can use the following script to convert/merge your individual XML files into one.''' (I use it for high latency networks).
Note: you must run this script from within the packages directory; it ignores badly formed XML documents (and prints a warning); you should remove your packages directory afterwards; it will overwrite your packages.xml file.
<source lang="bash">
#!/bin/bash
echo '<?xml version="1.0" encoding="UTF-8"?>' > ../packages.xml
echo '<packages>' >> ../packages.xml
for package in `ls *.xml`
do
xmlwf $package | grep "not well-formed"
if [ "$?" == "1" ]; then
cat $package | sed -e :a -e 's/<\(\(\/\)*packages\)[^>]*>//g;/</N;//ba' | sed -e :a -e 's/<?xml.*>//g;/</N;//ba' >>../packages.xml
fi
done
echo '</packages>' >> ../packages.xml
</source>
==See also==
* [[profiles.xml]] - defines the profiles.
* [[hosts.xml]] - defines the hosts.
* [[wpkg.js]] - WPKG engine.
* [[package dependencies]] - package dependencies.
[[category:Documentation]]
[[category:Installation]]
[[category:Config_Files]]
----
'''packages.xml''' es el fichero que indica como realizar las instalaciones, actualizaciones y desinstalaciones de los paquetes de software. En otras palabras, es la lista de todos los programas y scripts que pueden ser instalados o ejecutados en las estaciones de trabajo..
Este fichero se localiza en el mismo directorio que [[wpkg.js]].
[http://wpkg.org WPKG] no trabajará sin este fichero.
==packages.xml estructura==
La estructura básica de '''packages.xml''' es la siguiente:
<source lang="xml">
<packages>
<package
id="wpkg1"
name="Windows Packager sample 1"
revision="1"
reboot="false"
priority="0">
<check type="registry" condition="exists" path="HKLM\Software\wpkg\full\key\not\part\of\it" />
<check type="file" condition="exists" path="%PROGRAMFILES%\wpkg\wpkg.bat" />
<check type="uninstall" condition="exists" path="WPKG" />
<install cmd='msiexec /i (path to msi)'>
<exit code="0" />
</install>
<remove cmd='%PROGRAMFILES%\uninstall\uninst.exe -quiet' />
<upgrade cmd='msiexec /i (path to msi)' />
</package>
</packages>
</source>
Cada paquete tiene los siguientes atributos:
* '''id''' - un identificador único que representa al paquete. DeberÃa ser corto y representativo
* '''name''' - longer textual description of the package. This should be the full product name.
* '''revision''' - user created version number to represent the "version" of the specific WPKG package for this application. If you change the package, increment it. It can be the revision that the WPKG package is for, or the software application's version (though note such a strategy won't leave you room to change your WPKG package, for example when making an improvement or fixing a bug in the XML, other than when the software application is also upgraded).
** The following formats are supported:
*** an integer (1, 10, 1000, etc.)
*** dotted revision numbers (1.1, 2.1.4, 3.200.3987, etc.) ... introduced with WPKG 1.0
*** volatile revisions (1.2RC1, 1.5I32, 2.73M24, 1.65.b, etc.) ... introduced with WPKG 1.1.1 (see the changelog for more examples)
** If you like to keep track of the date you have last changed the package, because there is no better revision number, you can use the format YYYY.MM.DD (2010.07.27, etc.)
** In addition one can define a variable inside the package and use that as the revision, which is useful, if this is used in different places inside the package (package revision, path of installer, checks, etc.) ... introduced with WPKG 1.1.2:
<source lang="xml">
<package
id="firefox"
name="Mozilla Firefox"
revision="%PKG_VERSION%"
reboot="false"
priority="10">
<variable name="PKG_VERSION" value="3.6.8" />
</source>
* '''reboot''' - specifies if and how the system reboots when installing, removing or upgrading a given package.
** true - always reboot after processing this package.
** postponed - reboot after WPKG has finished processing all packages, if the package checks are successful after the action.
** anything else - do not cause a reboot because of this package. Other packages may still cause a reboot.
* '''priority''' - specifies a numeric value that determines in what order a package will be installed. The higher the number, the higher the priority, and so the earlier the package will be installed compared with lower priority packages. For example:
** 2 - installs these packages 1st
** 1 - installs these packages 2nd
** 0 - installs these packages 3rd
Note that a package installer with priority '5' would install before all these.
* '''execute''' ''(optional)'' - see [[Execute_once_/_always]]
== Check conditions / check type ==
Of course it would be unwise to launch the installer if the software is already installed. That's why there are "check conditions".
The check conditions are also used after the installer has finished to verify that the software has actually been successfully installed.
If no check statements exist in the package, WPKG will just run the install (or upgrade) commands and (as long as no error occurs) will add/update the package details in the local client database.
Check conditions are broken down into 4 categories:
*'''Registry''' - Checks the registry for conditions
*'''File''' - Verifies various information about files within the filesystem
*'''Uninstall''' - Checks the software installation registry key (as displayed in Windows' Add/Remove Programs section) for the existence of an existing package
*'''Execute''' - Executes a script and checks the returning errorlevel (since WPKG 1.1.0)
*'''Logical''' can also be used
===Registry===
Registry checks allow you to check for the existence of or a specific value in a registry key ('''Note''': for pre-1.0 versions,
it works on a registry value only, not a registry key!).
Beware, there is a limitation of the RegRead method used by WPKG's Registry checks to query registry values which contain backslashes ('\'). See the Execute section below to use instead to address this issue.
There are two possible conditions available for registry checks: ''exists'' and ''equals''.
<div style="margin-left: 30px">
'''exists''' - This checks for the existence of a registry key. If the registry key is found, the condition returns true, otherwise it returns false.
'''equals''' - This checks a specific value of a registry key. If the registry value is found and that value is equal to the supplied value, the condition returns true, otherwise it returns false.
</div>
Examples:
This checks for the existence of Adobe Reader within the registry:
<source lang="xml">
<check type="registry" condition="exists" path="HKLM\Software\Adobe\Adobe Reader\7.0" />
</source>
This checks to see if Firefox, US English, version 1.5.0.6, is installed:
<source lang="xml">
<check type="registry" condition="equals" path="HKLM\Software\Mozilla\Mozilla Firefox\CurrentVersion" value="1.5.0.6 (en-US)" />
</source>
===File===
File checks allow you to check for the existence of a file, check for a particular file's size, or examine version information about a file. There are several possible conditions available for file checks:
<div style="margin-left: 30px">
'''exists''' - This checks for the existence of a file. If the file is found, the condition returns true.
'''sizeequals''' - This checks the size of a file. If the file is found and the size equals the value supplied, the condition returns true.
'''versionsmallerthan''' - This checks the version of a particular file. If the file is found and the version is less than the supplied version number, the condition returns true.
'''versionlessorequal''' - This checks the version of a particular file. If the file is found and the version is less than or equal to the supplied version number, the condition returns true.
'''versionequalto''' - This checks the version of a particular file. If the file is found and the version is equal to the supplied version number, the condition returns true.
'''versiongreaterorequal''' - This checks the version of a particular file. If the file is found and the version is greater than or equal to the supplied version number, the condition returns true.
'''versiongreaterthan''' - This checks the version of a particular file. If the file is found and the version is greater than the supplied version number, the condition returns true.
</div>
Examples:
This checks for the existence of Adobe Reader within the filesystem:
<source lang="xml">
<check type="file" condition="exists" path="%PROGRAMFILES%\Adobe\Acrobat 7.0\Reader\AcroRd32.exe" />
</source>
This checks to see if Firefox US English version 1.5.0.6 is installed based on the file size of the executable:
<source lang="xml">
<check type="file" condition="sizeequals" path="%PROGRAMFILES%\Mozilla Firefox\firefox.exe" value="7183469" />
</source>
This checks whether the version of Firefox .exe that's currently installed is less than 1.5.0.6:
<source lang="xml">
<check type="file" condition="versionsmallerthan" path="%PROGRAMFILES%\Mozilla Firefox\firefox.exe" value="1.5.0.6" />
</source>
===Uninstall===
Uninstall checks allow you to check the Microsoft software installation registry keys (as displayed in Windows' Add/Remove Programs section) for the existence of a particular package. Microsoft maintains the list
of applications installed and available for uninstallation in the ''HKLM\Software\Microsoft\Windows\CurrentVersion\Uninstall'' registry key. The value in the DisplayName key of a particular package is what's matched by this check.
pre-1.1.0 versions of WPKG have only one condition available for this option: ''exists''.
<div style="margin-left: 30px">
'''exists''' - This checks for the existence of the particular software package in the installation database. If the package is found, the condition returns true.
</div>
Since version 1.1.0 this check is extended with several other conditions:
<div style="margin-left: 30px">
'''versionsmallerthan''' - This checks for the existence of a particular software package in the installation database and also checks the version of that software package. If the package is found, and the version is smaller than the supplied value, the condition returns true.
'''versionlessorequal''' - This checks for the existence of a particular software package in the installation database and also checks the version of that software package. If the package is found, and the version is less than or equal to the supplied value, the condition returns true.
'''versionequalto''' - This checks for the existence of a particular software package in the installation database and also checks the version of that software package. If the package is found, and the version is equal to the supplied value, the condition returns true.
'''versiongreaterorequal''' - This checks for the existence of a particular software package in the installation database and also checks the version of that software package. If the package is found, and the version is greater than or equal to the supplied value, the condition returns true.
'''versiongreaterthan''' - This checks for the existence of a particular software package in the installation database and also checks the version of that software package. If the package is found, and the version is greater than the supplied value, the condition returns true.
</div>
Examples:
This checks for the existence of Adobe Reader through the installation list:
<source lang="xml">
<check type="uninstall" condition="exists" path="Adobe Reader 7.0" />
</source>
This checks to see if Firefox version 1.5.0.6 is installed in the installation list:
<source lang="xml">
<check type="uninstall" condition="exists" path="Mozilla Firefox (1.5.0.6)" />
</source>
This checks for the existence of The Gimp 2.6.6 or higher through the installation list:
<source lang="xml">
<check type="uninstall" condition="versiongreaterorequal" path="GIMP" value="2.6.6" />
</source>
===Execute===
Execute allows you to execute any script which checks if an application is installed. WPKG checks the exit code of the script to determine the existence of the particular software package.
This type of check also allows very complex checks. For example there is a limitation of the RegRead method used by WPKG's Registry checks to query registry values which contain backslashes '\'. Now you can execute a batch script which checks for such registry values using 'reg query ...'.
There are several possible conditions available for execute checks:
<div style="margin-left: 30px">
'''exitcodesmallerthan''' - This checks the exit code of the executed script. If the exit code is smaller than the supplied value, the condition returns true.
'''exitcodelessorequal''' - This checks the exit code of the executed script. If the exit code is less or equal to the supplied value, the condition returns true.
'''exitcodeequalto''' - This checks the exit code of the executed script. If the exit code is equal to the supplied value, the condition returns true.
'''exitcodegreaterorequal''' - This checks the exit code of the executed script. If the exit code is greater than of equal to the supplied value, the condition returns true.
'''exitcodegreaterthan''' - This checks the exit code of the executed script. If the exit code is greater than the supplied value, the condition returns true.
</div>
Examples:
This evaluates true if the exit code is negative
<source lang="xml">
<check type="execute" path="\\path\to\script.cmd" condition="exitcodesmallerthan" value="0">
</source>
This evalueates true if exit code is 0 or negative
<source lang="xml">
<check type="execute" path="\\path\to\script.cmd" condition="exitcodelessorequal" value="0" >
</source>
This evaluates true only if exit code is exactly 0
<source lang="xml">
<check type="execute" path="\\path\to\script.cmd" condition="exitcodeequalto" value="0" >
</source>
This evaluates true if exit code is 0 or any positive number
<source lang="xml">
<check type="execute" path="\\path\to\script.cmd" condition="exitcodegreaterorequal" value="0" >
</source>
This evaluates true if exit code is any positive number
<source lang="xml">
<check type="execute" path="\\path\to\script.cmd" condition="exitcodegreaterthan" value="0" >
</source>
===Logical Conditions===
There can be zero or more conditions verified during the existence checks. If no conditions are supplied, WPKG attempts to install the package regardless of whether it's currently
installed or not. To facilitate using more than one condition, there is a 4th type of condition that can be added, called the logical condition. Logical conditions allow you to create
multiple conditions while checking for the presence of an existing package. Logical conditions are top level conditions, with the real check conditions as subnodes in the XML.
The following logical conditions are available: ''not'', ''and'', ''or'', ''atleast'', and ''atmost''.
*) both ''atleast'' and ''atmost'' do require the parameter ''value=''
Examples:
Let's say, for the sake of argument, that you have an Adobe Reader 7.0.8 package that you want installed, but you only want it installed on workstations
that are running Windows XP Service Pack 2 or higher, due to some strange incompatibility. Let's also say that some workstations can't be
upgraded to Windows XP Service Pack 2 until those workstations are upgraded from 256MB of memory to 512MB of memory. For a scenario like this, you could
(and probably should!) use multiple profiles and have those SP1 workstations in one profile, while the SP2 workstations are in another. However, just
for example purposes, let's say all workstations are in a single profile. You can provide a logical condition in order for only those workstations
running SP2 to be upgraded to Adobe Reader 7.0.8:
<source lang="xml">
<check type="logical" condition="or">
<check type="registry" condition="exists" path="HKEY_LOCAL_MACHINE\SOFTWARE\Adobe\Acrobat Reader\7.0\Installer\Updates\708" />
<check type="registry" condition="equals" path="HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows NT\CurrentVersion\CSDVersion" value="Service Pack 1" />
</check>
</source>
The 2nd condition here might seem counter intuitive, but remember that you're looking for the absence of things rather than the existence of things when you're writing
check conditions. What the above condition says is "Is Adobe Reader 7.0.8 installed or is Service Pack 1 installed? If either of these conditions equates to true,
the installation will be skipped. In this particular case, Adobe Reader 7.0.8 isn't installed, but the value of CSDVersion is Service Pack 1 (for the SP1 boxes)
so the software will not be installed.
Once all conditions have been tested, if the final result of the conditions is equal to false, WPKG will try to execute the "'''install cmd'''".
After it's executed, WPKG will check the exit code (should be 0 in this example) '''*and*''' verify all the checks.
If '''*any*''' of the checks are not met, software is considered '''*not*''' installed - so enter these values carefully!
Also, if no checks were specified, WPKG will say that the installation have failed. Although this is useful for cases where you want to install the package every time WPKG runs, you will probably want the installation without an error - see [[Execute once / always]] for executing packages without any checks.
Remember that you don't have to specify all three check conditions, usually one is enough: if the software you are about to install will show up in Windows' Add/Remove Programs (and not all do), it is sufficient to specify just the "'''uninstall'''" check.
==Actions==
WPKG understands several actions: '''install''', '''upgrade''', '''downgrade''', '''remove''' and '''download'''. Multiple commands for each of these actions can be listed in the config file and WPKG will execute them in the order they are listed.
The '''install''' commands are executed by WPKG when a new package comes into scope for a profile.
The '''upgrade''' commands are executed when a new revision of a package comes into scope. That is, when the '''revision''' number in the '''packages.xml''' file on the server is larger than the one in the local '''wpkg.xml''' file. Note that the upgrade commands will be run even if the check conditions are already met.
The '''downgrade''' commands are executed if the version installed on the client is newer than the one on the server side.
The '''remove''' commands are executed when a package is removed from a profile.
The '''download''' commands are always executed when used on the global package level. Since WPKG version 1.1.0 however, this command is also allowed as a sub-node of any of the other commands. This allows you to specify a download which is only downloaded for a specific command. This was implemented since it usually makes no sense to download the installation package again right before the remove commands are executed (which usually runs a local uninstall command which does not need the original installer). '''Note:''' If multiple install (or upgrade/downgrade/remove) commands are specified WPKG will download the the files of all command nodes of the same kind before starting to execute the commands in sequence.
In many of the examples in the [[:Category:Silent_Installers]] section, cmd.exe is executed to perform environment variable expansion and to use 'start /wait' to wait on the command being executed. This method of executing commands results in cmd windows appearing on screen. However, this method does not appear to be necessary. The current version of WPKG executes commands using the WScript.Shell.Exec() function and expands environment variables before execution. WPKG then waits until the command is completed before continuing.
The correct method of executing a command interpreter is to use the %comspec% environment variable, not specifying cmd.exe explicitly. This is needed to run commands that are built into the interpreter and are not separate executables.
When the output of a command (think of: copy,cacls) is too much, the command will fail. You have to redirect the output to NUL or a file (example: "%command% >nul").
Typical examples:
<source lang="xml">
<download url='http://wpkg.example.com/installers/some.msi' target="installers\some.msi" />
<install cmd="msiexec /qn /i %SOFTWARE%\package.msi" />
<install cmd="msiexec /qn /i %SOFTWARE%\package.msi" timeout="1800" />
<install cmd="%comspec% /c copy %SOFTWARE%\file.dll %WINDIR%" />
<remove cmd="msiexec /qn /x %SOFTWARE%\package.msi" />
</source>
The timeout option ([[Timeouts]]) tells WPKG how long to wait for the command to complete. It is in seconds and the default is 3600 seconds.
If the command you specify returns a value of "0" then wpkg assumes it was successful and continues with the next command, if any. If the command returns a nonzero value, then wpkg stops and logs a failure for the package. Sometimes nonzero exit codes are expected and you want to accept them. You can do this by adding exit code sections inside the install section, like this:
<source lang="xml">
<install cmd="msiexec /qn /i %SOFTWARE%\package.msi" >
<exit code="0" />
<exit code="259" />
</install>
</source>
If you don't care about exit code, use <code>exit code="any"</code>:
<source lang="xml">
<install cmd="msiexec /qn /i %SOFTWARE%\installer.exe /silent" >
<exit code="any" />
</install>
</source>
You can set a specific reboot action for certain exit codes with something like the following:
<source lang="xml">
<install cmd="msiexec /qn /i %SOFTWARE%\package.msi" >
<exit code="3010" reboot="true" />
<exit code="0" />
</install>
</source>
The options for the exit code reboot are:
* true - immediate reboot, without updating wpkg.xml
* delayed - reboot once the package action is complete and wpkg.xml is updated
* postponed - reboot once all the packages have been processed
Please note that the target value for a download action is always relative to the downloadDir defined in wpkg.js (and there's currently no configuration option to change this from the default of %TEMP%).
==Quick examples==
Other example - WPKG checks if the package is installed only in Windows' Add/Remove Programs before deciding to install it (to make sure it is not installed already):
<source lang="xml">
<package
id="wpkg3"
name="Windows Packager sample 3"
revision="1"
reboot="false"
priority="1">
<!--
This is a comment.
Checks in Windows' Add/Remove Programs only.
-->
<check type="uninstall" condition="exists" path="WPKG" />
<install cmd='%PACKAGES%\package.exe /quiet /install' />
<remove cmd='%PACKAGES%\package.exe /quiet /uninstall' />
<upgrade cmd='%PACKAGES%\package.exe /quiet /install' />
</package>
</source>
In the example below, there are no check conditions.
This means that WPKG will execute it each time - so this is rather useful for executing scripts that need to be run each time the machine is booted, than installing software:
<source lang="xml">
<package
id="backupfiles"
name="Makes backup of some file"
revision="1"
reboot="false"
priority="0">
<!--
This is a comment.
'''No check conditions; script will be executed *each time* wpkg.js is called - each time PC is booted.'''
-->
<install cmd='\\server\path\script.bat' />
</package>
</source>
Similar example, without any conditions, either.
Note the '''execute="once"''' entry - this means that that script will be executed only once. It is useful for the tasks you want
to do one time only, like disk defragmenting, some testing, changing printers etc.
<source lang="xml">
<package
id="backupfiles"
name="Makes backup of some file"
revision="1"
reboot="false"
execute="once"
priority="0">
<install cmd='\\server\path\script.bat' />
</package>
</source>
Similarly, you may want to execute a program or script each time - use "always" instead of "once". For more info on this functionality, check [[Execute_once_/_always|here]].
==Package dependencies==
Packages can also depend on other packages, see [[package dependencies]] for more info.
==Individual XML package files==
If you would rather keep your package XML description in separate files, you can of course do that: just create a <code>packages</code> directory where <code>wpkg.js</code> is, and place individual XML files there (i.e., thunderbird.xml, firefox.xml etc.). The syntax is the same as that of packages.xml.
Note, if you decide to keep all your packages in separate XML files, you still need a <code>packages.xml</code> file, which should at least contain an empty entry:
<source lang="xml">
<?xml version="1.0" encoding="UTF-8"?>
<packages>
</packages>
</source>
Here is an example of an individual XML file - note that it must contain <packages> at the beginning and </packages> at the end:
<source lang="xml">
<?xml version="1.0" encoding="UTF-8"?>
<packages>
<package id="setadminpassword"
name="Set admin password"
revision="1"
priority="999"
reboot="false"
execute="once">
<install cmd='cmd /c net user administrator password' />
</package>
</packages>
</source>
WARNING! Please note for this example: The password is visible in the local copy of wpkg.xml, so remove after installation, or better yet, use the command in a separate .bat file.
'''You can use the following script to convert/merge your individual XML files into one.''' (I use it for high latency networks).
Note: you must run this script from within the packages directory; it ignores badly formed XML documents (and prints a warning); you should remove your packages directory afterwards; it will overwrite your packages.xml file.
<source lang="bash">
#!/bin/bash
echo '<?xml version="1.0" encoding="UTF-8"?>' > ../packages.xml
echo '<packages>' >> ../packages.xml
for package in `ls *.xml`
do
xmlwf $package | grep "not well-formed"
if [ "$?" == "1" ]; then
cat $package | sed -e :a -e 's/<\(\(\/\)*packages\)[^>]*>//g;/</N;//ba' | sed -e :a -e 's/<?xml.*>//g;/</N;//ba' >>../packages.xml
fi
done
echo '</packages>' >> ../packages.xml
</source>
==See also==
* [[profiles.xml]] - defines the profiles.
* [[hosts.xml]] - defines the hosts.
* [[wpkg.js]] - WPKG engine.
* [[package dependencies]] - package dependencies.
[[category:Documentation]]
[[category:Installation]]
[[category:Config_Files]]