Automated Client Deployment

At sites that have a large number of KeyAccess client installs to perform, manually running the client installer on each computer may be impractical. This document references some techniques, tools, and documentation that facilitates large scale deployment. These are overviews and examples, your environment may have specific considerations related to these methods.

If you already have the client deployed and are simply looking to push out updates, please also reference our Client Self Update documentation.

Note: deployment of the KeyAccess client on file servers (for the purpose of auditing only) is covered in the Server Audits document.

Note: There are many mentions below of setting the hostname that KeyAccess communicates with. These are all using the traditional UDP method of simply putting in the FQDN of the server. However, customers of our hosted cloud instances, and optionally on prem implementations, can use https instead (which also offers secure communication of course). Simply use URL syntax for the hostname (e.g. https://myserver.mydomain.com) instead of just the DNS name (e.g. myserver.mydomain.com) and the client will use https instead of UDP.

Large scale deployment methods

KeyAccess client components can be installed as part of a cloned image for new computers - consult the Cloning document for important cautions and details.
a general purpose file deployment tool (e.g. SCCM/MECM, InTune) can be configured to install or upgrade the KeyAccess client files and settings - consult the complete File List document, the cloning document, and the OS Details appendix for details concerning client components and settings.
an "Application server" such as WTS (Windows Terminal Server) or WinFrame may be used to serve out the KeyAccess client along with server hosted application programs - consult the OS Details appendix for WTS support information. Note: the "Add/Remove" programs control panel should be used when installing KeyAccess in order to ensure that "Install mode" is enabled.
the client installer on Windows can be run with command line options - consult the documentation notes below.
the client installer on either Mac or Windows can be customized with site specific preferences for silent execution when logging onto the network - consult the documentation notes below.

Click here for Information on using SCCM to deploy the client.

Using SCCM to push the client installer should be pretty straight forward. The below screenshot should be similar across various versions of SCCM of the window for a custom package deployment where you can specify the various command line options detailed above. That is, in the Installation program field under Specify the command used to install this content specify something like "ksp-client-x64.exe -q -v PROP_HOSTNAME=keyserver.mysite.org"

Click here for Information on using InTune to deploy the client.

When using InTune to deploy KeyAccess, you'll likely want to use Microsoft's tool for making a "winapp" bundle from our ksp-client-x64.exe installer. Feed that bundle into the InTune action, and set the install parameters. Usually this is -q for quiet install, and -v PROP_HOSTNAME=yourserver.yourdomain.com for setting the server address.

InTune seems to requires an uninstall string even if you don't allow uninstall in the action, so note you can use the following:

msiexec.exe /x {E23D1D2C-1762-11D5-A8D2-00C04FA35723} /q REBOOT=ReallySuppress

It's also probably a good idea to set a Detection Rule. You can simply set this to detect if keyacc32.exe is in the default installation path of c:\Program Files\Sassafras K2\Client. This works well if you simply want to ensure KeyAccess is installed of whatever version you have in the InTune action, and incremental updates are being served out by our auto update feature. If you want to get more specific with version checking, you can leverage the version string in the Registry at HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\KeyAccess\Settings.

Deploy and Update through Active Directory GPO

There are several ways to leverage Group Policy in AD to deploy and update the KeyAccess client. This documentation gives ideas but can not cover all aspects of your potential infrastructure implementation.

One method is to use a startup or shutdown script that calls installers with necessary command line options, e.g.:

\\server\share\ksp-client-x64.exe -gpo -q -v PROP_HOSTNAME=keyserver.mysite.org

The command line options above will be the most common for an initial deployment, details on the parameters are below. It is assumed you to have a network share that is machine accessible that is used for other GPO deployments.

Triggering on startup or login for a script may not be optimal however, so another method is using a scheduled task.

Click here for a walkthrough of making a Scheduled Task GPO.

In Group Policy Management create a GPO on the OU you want to deploy KeyAccess to.
Edit the GPO and navigate to Computer Configuration -> Preferences -> Control Panel Settings -> Scheduled Tasks
Create a new Immediate Task "(at least Windows 7)" if you want this to be a one off deployment. You can use Scheduled Task if you want to set up say a weekly job where it will check for and install a new client version. And of course you can do both in one policy to cover deploy and upkeep.
On the General Tab of the task Properties:
- Set a desired name for the Task (seen on client system in Task Scheduler). This is really only significant if you'll be setting up a regular schedule.
- Set the task to run as NT AUTHORITY\SYSTEM by clicking "Change User or Group", typing SYSTEM, Check Name, Choose SYSTEM.
- Set to Run whether user is logged on or not
- Check Run with highest privileges
- Set Configure for to Windows 7, Windows Server 2008R2
On the Actions tab create a new Action:
- Set Action to Start a program
- Set Program/script to the full network path to the client installer on your share, e.g. \\server\share\ksp-client-x64.exe
- In Add arguments put in -q -gpo -v PROP_HOSTNAME=serveraddress where serveraddress is the FQDN or IP of your KeyServer. You can also add -v PROP_FORCEHOST=1 if you are changing your server address (migrating) and -v PROP_AUDITNOW=1 if you want to force existing clients to do a fresh audit on install.
On the Common tab, if you make this an Immediate Task, check the box to "Apply once and do not reapply". This makes it a truly one time only action.

Deploy through PowerShell

If you have an environment configured to allow remote PowerShell administration, you could also use that to send an install command. An example could be something like this:

Get-ADComputer -Filter * -SearchBase "OU=myOU,DC=mydomain,DC=tld" | foreach {

    Invoke-Command -ComputerName $_.DNSHostname -ScriptBlock {

        & cmd.exe /c "\\server\share\ksp-client-x64.exe -gpo -q -v PROP_HOSTNAME=keyserver.mysite.org"
    }
}

Please consult Microsoft documentation for requirements on using PowerShell remotely such as Remote Requirements.

Windows Installer command line options

The following command line options are available on Windows (see below for Mac options). There may be others for specific needs rather than general use - if you need something in particular don't hesitate to contact Sassafras Software Support.

Options to make a quiet install and specify a server address:
-q - do a "quiet" install that won't display any UI, and suppresses restart.
-v PROP_HOSTNAME=keyserver.mysite.org - specify the KeyServer host name or IP address

Options that determine when to install KeyAccess or skip the install, based on versions:
-new - only install if there is no version of KeyAccess installed - do not change an existing install
-upg - install if there is no KeyAccess installed, or if an older version is installed
-gpo - install only if this version is not already installed (install if KeyAccess is not already installed, or if a different version is installed)

You should only specify one of the prior three options (-gpo, -new, -upg). The following table might help understand these options:

	-new	-upg	-gpo	no option (default)
no KeyAccess installed	install	install	install	install
older KeyAccess installed	do not install	install	install	install
same KeyAccess installed	do not install	do not install	do not install	install
newer KeyAccess installed	do not install	do not install	install	install

Other Options

Note that each option must be preceded by -v as shown or it will be ignored.

-v PROP_AUDITNOW=1	force an audit to complete immediately after install, even if no user is logged in (default)
-v PROP_CONTROLPANEL=0	do not install the KeyAccess Control Panel (not recommended)
-v PROP_FORCEHOST=1	if the client already has a KeyServer address, overwrite with the value passed as PROP_HOSTNAME
-v PROP_KEYCHECKOUT=1	install the KeyCheckout utility
-v PROP_KEYVERIFY=0	do not install KeyVerify (not recommended)
-v PROP_REBOOT=0	do not reboot after install
-v PROP_LAUNCH=1	launch KeyAccess after install (default)
-v PROP_QUITALL=1	quit all instances of KeyAccess before install (default)
-v PROP_LOCKED=1	do not allow changes to the KeyServer host inside the KeyAccess Control Panel
-v PROP_SITE=value	populate a value on the client which will appear in the Department field of the computer record
-v PROP_SHORTCUTS=0	do not create Start Menu shortcuts
-v ARPSYSTEMCOMPONENT=1	hide from Add/Remove Programs
-v PROP_TRUST={0\|1\|2\|10}	set the Trust level
-v PROP_SECURITY={0\|1\|2}	set the Security level
-v PROP_USERNAME=[reg]	use the given reg or sys value as the username instead of user ^{e.g.<HKEY_LOCAL_MACHINE\System\CurrentControlSet\Control\ComputerName\ComputerName\ComputerName> or ^%AppStream_UserName^%}

Options that determine what architecture to run on (vs aborting the install):
-platform 32 - only install if the client OS is 32-bit
-platform 64 - only install if the client OS is 64-bit

Our recommendation is to always install the same bitness as the OS. While the 32 bit client will run under a 64 bit OS, it will be limited in functionality for tracking certain obscure applications.

Embedding installer options in exe name

Note that on Windows, all of the above options can be embedded in the file name of the installer, so that you end up with an exe that doesn't require any additional parameters (e.g. could be double-clicked). To do this, add an @ symbol just before .exe. Then in between the @ and the . add any parameters you would otherwise pass to the exe, replacing spaces with + signs. For example, you might name a 64-bit installer:

ksp-client-x64@+-platform+64+-gpo+-v+PROP_HOSTNAME=keyserver.mysite.org.exe

Note that for this example we have not included the "-q" parameter. If we imagine a user double-clicking this installer, we don’t want it to silently run without any feedback.

Command Line Functions

Note that once installed, you can also call certain functions from the command line. The most common is sending a GPO or command by other management system to force clients to perform an audit. This is useful if you want clients to report in without waiting for a user to log in to trigger a session and scheduled audit.

keyacc32.exe -auditonly -auditnow

You can also do this on a Mac and Linux system with:

sudo killall -USR1 karl

If you require an MSI based installer, you can use a utility named k2clientconfig.exe. k2clientconfig is a command line utility found in the Installers\Windows Installers\Misc\ folder of the Sassafras image archive — or download the latest version from the Sassafras Software web site. Note that using k2clientconfig.exe to embed the install options in the exe is a legacy function and will remove the digital signature from the installer. For this reason, it is preferable to use command line options to the exe, as described above. Using the exe is also more feature rich in some ways than using the msi, so we recommend using the exe methods whenever possible. If your deployment mechanism only supports msi (as seems to be the case with InTune), you can use this utility to extract the MSI and then use the property flags above to specify the host as with the exe.

Deploying on Mac OS X

On Mac there are no command line options for package installs, but you can still do a silent (remote) install. This can be done in a terminal or with a script using the following two commands:

defaults write /Library/Preferences/com.sassafras.KeyAccess host keyserver.mysite.org
installer -tgt / -pkg ksp-client.pkg

As with all plist files, the format is xml based. While you can edit the plist manually following the normal syntax, it is recommended that you use defaults write to ensure there are no issues with file locking and to avoid issues with binary format. For deployment, it is best to write the settings before running the client installer. KeyAccess launches immediately after install so it is best to have the needed settings in place at launch time. The plist settings can be applied after install as well to make modifications, and you can kill the KeyAccess process to make it reload with the new settings as our launch agent will ensure respawn.

Other settings can be put into the plist with defaults write as well, including properties like site (department), assetLocation and other custom properties, as well as the trust and security Secure settings. While no longer recommended due to security impacts, k2clientconfig for Mac is a utility to modify the package installer and set defaults without the need to modify the plist prior to install.

You can use tools such as Apple Remote Desktop for deployment, as well as systems like JAMF (click the link for our blog on this).

Deploying on Linux on a command line

On Linux the KeyServer address can be specified during install using the env command. The installation syntax varies for different specific OS's - two examples are shown below:

sudo env KA_SERVERHOST=keyserver.mysite.org dpkg -i KeyAccess_version-build_platform.deb

sudo env KA_SERVERHOST=keyserver.mysite.org rpm -U KeyAccess-version-build.platform.rpm

For details about other syntax and additional command line options, refer to the Linux Client Deployment documentation.