Required steps

1. Copy content of YSoft SafeQ Client v3 Update Packages <build>.zip to directory <JobService>\spooler-update

2. Edit <JobService>\configuration\local.json and add the following, make sure to fill in the right FilePath:

   "SpoolerUpdateOptions": {

   "PackageMonitoringInterval": "00:10:00",

   "PackageSigningCertificate": {

   "FilePath":"C:\\SafeQ6\\JobService\\spooler-update\\cert-2022.cer",

   "Password":""

   }

   }

   • .cer from FilePath needs to be trusted by the workstations.

     • To verify trust copy the file to the Windows workstation and double-click it.

     • Go to tab "Certification Path", "Certificate status" must show "This certificate is OK".

   • Configuration options explanation:

     • PackageMonitoringInterval

       • Interval at which the spooler-update folder will be scanned for new update package.

       • Format: DD:HH:MM

     • PackageSigningCertificate

       • Certificate that was used to sign the update packages. This is sent to client application with the update command, client application uses this to verify the update package (see below).

       • FilePath - Path to the TLS certificate (YSoft SafeQ Job Service prioritizes certificate in the store over certificate on file path)

       • Password - Password for the certificate on the path

3. Restart YSoft SafeQ Job Service

4. Wait for client applications to auto update

YSoft SAFEQ Client v3 - additional possible configuration

If needed, update mechanism can be re-configured in section SpoolerUpdateOptions inside <Spooler>\versions\latest\configuration\local.json.

Normally no changes on the client application side are necessary, the settings listed below reflect the default values that will be used also when SpoolerUpdateOptions is not defined at all.

Available configuration:

• RequireValidSignature - Client will validate the signature of the package against the certificate from the server

• RequireTrustedCertificate - Client will execute the update package only if the underlying operating system trusts the certificate

• RequireMatchingCertificateFields - Client will execute the update package only if the certificate's subject contains required fields (see RequiredCommonNames and RequiredCountries)

• RequiredCommonNames - Client will check whether the certificate contains all of these common names

• RequiredCountries - Client will check whether the certificate contains all of these countries

How the Client v3 validates a new update package

1. JobService sends the information about update package based on manifest file

2. Client v3 downloads the update package

3. Client v3 checks if RequiredValidSignature option is true

   1. Client v3 verifies if the certificate is trusted (based on RequireTrustedCertificate option)

   2. Client v3 verifies certificate Common Name and Country (based on RequireMatchingCertificateFields option)

   3. Client v3 verifies update package (based on packageSignature from manifest file and certificate)

Update package requirements

• The package must be a zip file

• When creating a custom update package:

  • Make sure that once you extract it then the extracted folder will contain the YSoft.Spooler[.exe] executable in it and not another directory. The executable file has to be in root folder in the package. Name of this file should contain chars "a-zA-Z0-9.".
    

  • You should be aware that YSoft SafeQ Spooler might be updating across multiple versions (Spooler version 1 and the latest version is for example 4). That means (if it applies to you particular update package) that for example the latest package must contain configuration migrations for all intermediate versions.
    

• The package must be singed and the signature must be included in the package manifest file. For more information see section Manifest file structure below.
  

How to publish update package

Update packages are published to a folder <JobService>\spooler-update.Once the update package is in that folder, it becomes available for clients.

Spooler updates folder structure

Manifest file structure

Example of custom update procedure

Following is an example of a procedure which an update script for YSoft SafeQ Client v3 must implement

1. Migrate configuration files (optional - there might not have been changes between versions)

2. Stop all YSoft SafeQ Client v3 related services (or processes)

   1. YSoft SafeQ Spooler

   2. YSoft SafeQ Client v3 (user facing application)

3. Change versions/latest symlink to target to your new version

4. Start all YSoft SafeQ Client v3 related services (or processes)

You can see how the folder structure of deployed YSoft SafeQ Client v3 looks like at Deployment of YSoft SafeQ Client v3.

Log files

The process of auto update can be reviewed in:

• <Spooler>\versions\<build>\logs\spooler.log

• <Spooler>\versions\<build>\update.log

• <JobService>\logs\jobservice*.log

Testing auto update

To test the auto update process without having to wait several hours for it to complete:

• Update <Spooler>\versions\latest\configuration\local.json as follows:

  "StatusReportingOptions": {

     "ReportingInterval":"00:02:50",

     "MaxJitter": "00:00:10"

  }

• Restart YSoft SafeQ Spooler service

Client will report its version to the Job Service 10 seconds after the service restart and also in intervals 2 minutes 50 seconds (+-10 seconds). So the update will start in a few minutes.

The most common issues