Client Self-Updates

Starting with version 7.4.1, on Windows and on Mac OS X, KeyAccess has the ability to update itself automatically without user interaction

Details of the update — when it happens, what version is installed, and other settings — are configured centrally on the server. Client versions and newer for Windows and and newer for Mac are required for this function. Clients will fetch the upgrade instructions from the server and install the new version even if no users are logged into the computer. Installs are silent so there is no interruption to logged in users.

Note: Because the clients check for update information at various client triggered events (e.g. boot time), and they perform updates at a random 48 hour spaced time, it is possible a client could take several days before it updates. These mechanisms ensure a gradual roll out that does not tax the infrastructure. This means you should wait 3 days from the time you enable a new update until you question if there is an issue with any given client system getting it.

The client-side settings that are already in place, such as the KeyServer address, are retained. It is possible to change certain settings during the update, but typically this will not be necessary. It is important that you use the installers as they are, without modification (by k2clientconfig or otherwise). This because the installers are digitally signed by Sassafras, and the self-update process will verify the signature before using the installer file. Any modification will invalidate the signature.

While the update instructions are stored on and distributed by the KeyServer, the actual client installers must be stored on and served by an HTTP(S) server. This can be any server you choose, as long as it is accessible to your client computers. As of 7.7 this functionality is built in to the Web UI, along with a "one click" option to enable the updates.

Configuring The Update

7.7 and Newer

As of Sassafras KeyServer Platform 7.7 you can simply log in to the Web UI as an administrator and go to Settings -> Updates. If there is a newer client version available from Sassafras, there will be a notice of this. You can simply click the Accept button to have the new clients downloaded to the server and update the settings for you. Be sure to click Save to apply the settings and activate the updates.

New Client Updates

Older versions and Manual config

Configure the update settings in KeyConfigure under Config -> KeyAccess Version Control. The most important setting is the location of the client installer. Configuration for each client platform is kept separate, since each platform has a different installer. Put the installer(s) on the web server first, then enter the URL. You can test that the file is accessible by clicking the refresh icon. This will also determine the version of the client contained in the installer. It is important that the version displayed in this dialog is updated any time you change the installer on the web server.

The steps below are sufficient to instruct clients how to update.

  1. Place the client installers (one for each platform you have) on a central web server that is accessible to all clients
  2. In the Client Update dialog, for each platform, set the installer URL and click the refresh icon to update the version displayed.
  3. Check the “Enable Auto-updates until” checkbox and do not enter a deadline

When all needed platforms have been configured in this way, click OK. Each client checks in regularly to get the latest update instructions. Once each day (macOS) or two (Windows), the client update process will run (for more information on the scheduled tasks and considerations for state management like Deep Freeze, see TN3704). First, the process will determine whether the update applies to that particular computer. For example if the latest client is already installed, no update is needed. If the client determines that the update applies, it downloads the proper installer from the specified URL on the web server. Assuming the digital signature is valid, the installer is then executed to perform the update.

In most cases, the client will be running when the upgrade happens. The upgrade process will stop the running client before installing the new software, and then silently start the new client once the upgrade is complete. The upgrade process does not initiate a computer restart, but in some cases some of the new components will not be in place until after the client computer restarts.


Similar to standard client Deployment there are properties you can specify for the client installations. Generally you don't need to change things for simple upgrades, but you can use this to deploy new default settings if needed. These properties are set per client version (per tab). Much like tags, type a property and hit enter to add it to the window. Again, you generally do not need to use these as upgrades keep all prior version client settings, and this process inherently does things like close the running process, silently install, and then start the new process with no reboot.
The following properties are valid for self updates. Some properties on the deployment page should NOT be used here as they are implicit (like silent install and don't reboot)

PROP_LOCKED=1 do not allow changes to the KeyServer host inside the KeyAccess Control Panel
PROP_USERNAME=# value used for user name (Mac ONLY):
  • 0 - default value that the standard OS routine provides
  • 1 - computer name
  • 2 - long user name
  • 3 - short user name
  • PROP_COMPNAME=# value used for computer name:
  • 0 - Sharing name on Mac, Host name on Windows (same as 3)
  • 1 - locally configured host name
  • 2 - canonical host name
  • 3 - canonical host name, truncated to first component
  • 4 - locally configured host name, truncated to first name component
  • PROP_SITE=value populate a value on the client which will appear in the Department field of the computer record
    PROP_TRUST={0|1|2|10} set the Trust level
    PROP_SECURITY={0|1|2} set the Security level
    PROP_NOURL=1 disable URL tracking (privacy or security reasons)

    Generally not needed for upgrades, but could be used to help migrations:

    PROP_FORCEHOST=1 if the client already has a KeyServer address, overwrite with the value passed with PROP_HOSTNAME
    PROP_HOSTNAME specify the KeyServer host name or IP address
    PROP_NUKEAUDIT=1 clear the previous local audit so it is rebuilt

    Download URL

    Client installers are downloaded over HTTP(S) from any web server you choose. This can be a central web server for your organization, or an internal web server accessible to the client computers. As of 7.7 this is handled automatically in the Web UI of your Sassafras Server.

    Coverage Target

    Updates can be applied to a portion of all clients. This gradual update is randomized — you set a percentage of clients that should be updated, and then statistically that number of clients will be updated. As needed, this percentage can be increased up to 100%, at which point all clients will have been updated. This is useful for spreading out network load so all clients aren't trying to download the updater at the same time. Note that the random seed on the scheduled time does provide some spread already, so for most settings this option is not necessary.

    Security Measures

    The main protection against malicious parties utilizing the self-update feature is the digital signature of the installers. The update program that is already present on the client computer will check the signature of the downloaded installer before using it. The signature must be valid, and must also have been created using Sassafras Software's private signing key.

    The upgrade instructions are stored in a file that is read-only for non-administrator accounts. On Windows this file is stored at \ProgramData\KeyAccess\kami.xml. On Mac OS X the file is at /Library/Preferences/KeyAccess/kami.xml. Keep this file accessible only to admin accounts so it cannot be modified by normal users. But even if this file is changed, the digital signature check protects against installation of unsanctioned software. Modification of this file could disable updates, or could cause an older version of the client to be installed.

    While it is not necessary, using an HTTPS URL for the installers will add one more security obstacle.

    Note that the client can always be updated using external distribution mechanisms, such as Group Policy Objects. The self-update feature of the client can be disabled completely if there are security concerns about its operation.

    Old Versions

    While older versions of KeyAccess cannot self-update, they can be configured to receive bulletin messages asking them to update. This is done in the Old Version tab. Users of older versions can either receive a warning, or a message that they must upgrade in order to use managed programs (in which case they will not be able to use managed programs until they get a new version).

    There are various client versions in which new functionality was introduced, which may make these versions a natural choice for a cutoff.

    • Prior to, KeyAccess cannot respond to an Observe Policy. Usage which should be logged on these older clients is instead ignored (usage of programs with Manage Policies is recorded as usual).
    • Prior to, KeyAccess cannot observe or manage unkeyed usage. Only keyed programs can be managed on these older clients.
    • Prior to 6.0, KeyAccess does not do an audit of installed programs.
    • Prior to 5.2, KeyAccess does not choose a unique computer node ID, so will not appear in the Computers window.

    The version control setting will cause a dialog to appear on client computers, but whether your users contact you or not is up to them. You may wish to sort the Computers window by Version, in order to proactively identify computers with old versions of KeyAccess.

    Note that if you are able to deploy software, updating KeyAccess is very easy. The KeyAccess installer can be customized in such a way that a silent install can be done remotely, e.g. via GPO - for more details read the Deployment documentation.