Skip to content

Installation and Usage

Jump to bottom
Nils Thiele edited this page Sep 21, 2016 · 13 revisions

Content:

#Installation - Installer The easiest method of installing, updating and removing WPKG-GP Client is the precompiled installer (Inno Setup) found on the releases page, no additional steps are necessary.

If the installer is run from cmd or wpkg you can supply it with your custom client configuration file. If no custom ini is supplied it will default to the example configuration INI. Currently there is no way to configure the client through the installer gui, but this is planned for the future.

WPKG Example package with silent install option and custom ini:

<package
    id="wpkg-gp-client"
    name="WPKG-GP Client"
    revision="%version%"
    reboot="false"
    priority="1" >

	<variable name="version" value="0.9.6" />
	<variable name="CLIENTINI" value="%SOFTWARE%\wpkg-gp\client\wpkg-gp_client.ini" />
	<variable name="CLIENTINI" value="%SOFTWARE%\wpkg-gp\client\wpkg-gp_client_test.ini" hostname="^(ET-236-7020-1|pool-218-test|IT-204-7010-1)$" />

	<check type="uninstall" condition="versiongreaterorequal" path="WPKG-GP Client" value="%version%" />

	<commands>
		<command type="install" cmd='"%SOFTWARE%\wpkg-gp\client\wpkg-gp-client_v%version%.exe" /silent /norestart /SUPPRESSMSGBOXES /RESTARTEXITCODE=101 /ini="%CLIENTINI%"'>
			    <exit code="0" />
                <exit code="101" reboot="postponed" />
		</command>

		<command type="upgrade" include="install" />

		<command type="remove" cmd='"%PROGRAMFILES%\WPKG-GP Client\unins000.exe" /silent' architecture="x86" />
		<command type="remove" cmd='"%PROGRAMFILES(X86)%\WPKG-GP Client\unins000.exe" /silent' architecture="x64" />
	</commands>
</package>

For all possible Inno Setup command line switches take a look at the official documentation.

#Installation - Manual

If you don't want to use the prebuilt installer you can still install WPKG-GP Client manually.

Copy the WPKG-GP-Client directory found in the dist directory after compilation (pyinstaller) or from a installed version of the installer to a directory of your choice. It only has to be readable for normal Windows users. In the further instalation steps WPKG-GP Client is installed in %PROGRAMFILES%\WPKG-GP-Client.

We want the Program to autostart with every user that logs on to the system, for this we need to create a new Expandable String Value in HKLM\Software\Microsoft\Windows\CurrentVersion\Run that contains the path of the WPKG-GP Client executable. This can be done with regedit.exe or from the command line with the following command:

REG ADD "HKLM\Software\Microsoft\Windows\CurrentVersion\Run" /v "WPKG-GP Client" /d "%PROGRAMFILES%\WPKG-GP-Client\WPKG-GP-Client.exe" /t REG_EXPAND_SZ'

Besides the autorun entry the program itself needs a registry key in the HKEY_LOCAL_MACHINE\Software hive to function correctly. It will use this to store information of a pending reboot system wide. If user A runs a wpkg update which demands a reboot this information is also available to WPKG-GP Client that runs in the session of user B.

You have to create following registry key for this to work HKLM\Software\Wpkg-GP-Client. To do this using the command line you can use the following command:

REG ADD "HKLM\SOFTWARE\Wpkg-GP-Client" /v "RebootPending" /d "None" /t REG_EXPAND_SZ

To allow normal users to have write access to this key you have to change its permissions using regedit.exe and allow users full access. To do this using the command line there is a tool preinstalled in windows name regini.exe which applies registry informations from a text file. I have added a my regini configuration file to this repository in the Tools folder ( wpkg-gp-client-registry-perm.ini ).

regini "%SOFTWARE%\wpkg-gp\client\wpkg-gp-client-registry-perm.ini"

The last thing the WPKG-GP Client needs to work is a valid wpkg-gp_client.ini configuration file. A sample one can be found here.

For more information on the configuration of WPKG-GP Client have a look at the next chapter.

You can find a sample wpkg package file that will do all of those commands here.

#Configuration WPKG-GP Client has several options and function which are configured using the wpkg-gp_client.ini configuration file. Without this file available in the root of program directory the application won't start!

wpkg-gp_client.ini example:

################################
## WPKG-GP Client CONFIG File ##
################################

[General]
# Inform user that wpkg wasn't run for a specific time, default is 14
# Default: False
# Alternatives: True | False
check last update = True
last update interval = 14
# Add close button to tray
# Default: False
# Alternatives: True | False
allow quit = False
# Check LOG for errors from bootup wpkg-gp execution
# Default: False
# Alternatives: True | False
check boot log = False
# Check if VPN is connected (Only working with Cisco AnyConnect ATM installed in default folder)
# Default: False
# Alternatives: True | False
check vpn = False
# Specify the timeout in seconds after a which a shutdown/reboot will be initiated
# Default: 30
shutdown timeout = 30
# Specify custom help file
# Default: Default
# Alternatives: Default | %RELATIVE_PATH_TO_HELPFILE_FROM_INSTALL_DIR%
help file = Default

[Update Check]
# Select update check method
# Default: False
# Alternatives: wpkg-gp | updatefile | False
method = wpkg-gp
# Specify interval for automatic update checks in minutes, if False or 0 it wont check for updates automatically.
interval = 30
# URL to WPKG-GP Client update file, needs to be set for method = updatefile
update url = https://YOUR_WEB.SERVER/packages.xml
# Filter what pending tasks should be displayed (update, install, downgrade, remove), seperate by ";" without spaces.
# Default: install;update;downgrade;remove
# Example: install;update
filter =
# Blacklist what packages the user wont be informed about by package NAME, they will still install.
# Entries can be only the first letters which will be compared to the packages, seperate by  ";" without spaces.
# Default: Not Set
# EXAMPLE: micro;fire
#          would block the packages with the names Micosoft Office, Microsoft Visual Studio, Firefox , Firebird
#          but not Mozilla Firefox
blacklist =
# Check after startup if updates are available.
# Default: False
# Alternatives: True | False
start up = False

Most options are self-explanatory with the added comments.

There are 2 methods for checking for pending updates/tasks (method = wpkg-gp or updatefile). the "wpkg-gp" method uses wpkg-gp to query for pending tasks, it will detect pending installs, updates, downgrades and removes. You can filter what the user will be notified about by change the "filter" setting. The "updatefile" method only works for updates and you have to add a valid url to a WPKG-GP Client update file. For more information on this take a look at the next chapter.

Using both methods you can blacklist packages by the wpkg package name, this is useful for packages you dont want to bother the user with or packages executed every time wpkg-gp syncs (execute=always), those would otherwise show up as new install on every check. Check the comments in the config file for more information.

The VPN detection only informs the user if a vpn connection (using Cisco AnyConnect) is active and if he wants to continue updating the system. This features in only tested with the client supplied in our organisation. It needs to be installed in either %PROGRAMFILES%\Cisco\Cisco AnyConnect Secure Mobility Client\ or %PROGRAMFILES(X86)%\Cisco\Cisco AnyConnect Secure Mobility Client\.

#Generating updates file for WPKG-GP Client WPKG-GP Client relies on a special xml file to inform the user of pending updates if the method "updatefile" was configured in the configuration.

This file should be generated on the server and contains every package id and current revision number, no other information is added. WPKG-GP Client downloads this file from a webserver and compares it to the local wpkg.xml on the client. As you may guess this only works for software that is allready installed on the client system and it won't inform the user of other tasks (new installs, removes).

A small python script will generate this file automaticly and should be able detected even nested variables (revision="%version%).

You can find this generator in the Tools folder of this repository (create_pkg_ver_list.py, xmlpp.py). It should work on all system with python installed (2.7) but you can also find a precompiled windows version on the releases Page.

The tool is commandline only, you specify a input folder (wpkg root directory) and an output file.

Precompiled Windows Version: create_pkg_ver_list.exe -f %INPUTFOLDER% -o %OUTPUTFILE%

Python Version (xmlpp.py needs to be in the same folder): python create_pkg_ver_list.py -f %INPUTFOLDER% -o %OUTPUTFILE%

Example (Linux SMB server with a small HTTPS server): python create_pkg_ver_list.py -f /media/wpkg -o /var/www/wpkg/packages.xml

The process can then be automated using windows scheduled tasks or a cronjob on linux.

At the moment the tool only parses all files in the packages folder as well as packages.xml in the wpkg root directory

#Usage After a user logs in WPKG-GP Client resides in the system tray, if you can't see it right away, it may be grouped with other hidden icons that will only appear if there is an active notification.

WPKG-GP Client residing in the system tray

Right-Clicking the icon will open a popup menu with the available options:

Tray popup menu

If you configured an automatic update check in a specific interval it will display a notification bubble if updates are available:

Tray update notification

Doubble clicking the tray icon, selecting the "System update"-Option from the popup menu or clicking on a update notification bubble will open the upgrade dialog window:

update dialog

If you want the system to shutdown automaticly after the installation is done you can check the checkbox, while wpkg is running this can still be checked or unchecked.

The user will be presented with another warning dialog if he chooses to start the update:

update in progress

During the wpkg process the user will be informed with current progress:

update in progress

After the wpkg process is finsihed the user can close the dialog or view the log file of the finished process:

update done

update done

If an error is detected during an installation the log will be opened automaticly.

If a restart is necessary the user will be informed and given the option to reboot right away or later:

restart necessary

If a restart is pending WPKG-GP Client will block another update run:

restart necessary

If a reboot or shutdown is scheduled it wont shutdown right away and the process can even be canceled using the popup menu:

restart necessary

There are a few other dialogs and windows a you may encounter.

If there is no connection to the wpkg drive/server:

restart necessary

If the system was blacklisted:

restart necessary

If an active VPN connection was detected:

restart necessary

If the system wasn't updated in a while (can be configured in the config file):

restart necessary

If the application has no access to the registry:

restart necessary

Clone this wiki locally