Deployment of YSoft SafeQ Job Service
Job Service is a component responsible for handling the communication between Spooler controller and Spooler/YSoft SafeQ Client v3. It is also responsible for communication with other Job Service components and a persistent layer (YSoftSQ-JSDL). It handles info about jobs, users and configuration. Job Service is deployed server side and is a necessary part of the architecture when using YSoft SafeQ Client v3. For advanced configuration please visit the links below.
Installed services
YSoft SafeQ Job Service can be installed using the PowerShell script included in the package – install.ps1. The script will install 2 Windows services:
- YSoft SafeQ Job Service (YSoftSQ-JOB-SERVICE)
- YSoft SafeQ Job Service Distributed Layer (YSoftSQ-JSDL)
Prerequisites
- IP addresses or hostnames of all Site Servers where YSoft SafeQ Job Services will be installed in the cluster.
- The IP address of YSoft SafeQ Spooler controller running on the same machine as is the installation destination of Job Service.
- SSL/TLS certificate which is trusted in the infrastructure
- Used for HTTPS
- Without the certificate, YSoft SafeQ Job Service will use a self-signed certificate
- Will be provided via HttpsCertificatePath and HttpsCertificatePassword configuration values in the install script, see section How to
- Asymmetric key pair packaged as a certificate for signing access tokens
- YSoft SafeQ Job Service needs an asymmetric key pair to sign and validate access tokens (JWTs). This key material must be packaged as a certificate.
Must be the same for all YSoft SafeQ Job Services in the cluster
- See Generating certificate for signing access tokens/secured SSL connection to generate such certificate
- Will be provided via SigningCertificatePath and SigningCertificatePassword configuration values in the install script, see section How to
- The Microsoft Visual C++ Redistributable 2019 is installed on the YSoft SafeQ Job Service server.
How to
Run install script install.ps1
Example of script usage
This is an example of how the script can be called.
BASH.\install.ps1 ` -NrgAddresses SITE_SERVER_1,SITE_SERVER_2,SITE_SERVER_3 ` -SigningCertificatePath "PATH_TO_SIGNING_CERTIFICATE" ` -SigningCertificatePassword SIGNING_CERTIFICATE_PASSWORD ` -HttpsCertificatePath "PATH_TO_SSL_TLS_CERTIFICATE" ` -HttpsCertificatePassword SSL_TLS_CERTIFICATE_PASSWORD
Install script arguments
Argument | Description | Required | Default value | Example |
---|---|---|---|---|
-InstallPath | A path where YSoft SafeQ Job Service will be installed. | no | <install_dir>/JobService | <install_dir>\JobService |
-SpocAddress | SpocAddress Changing SPOC address to anything but localhost is not supported and will probably result in some features not working correctly. Address of YSoft SafeQ Spooler Controller to which will YSoft SafeQ Job Service connect. | no | localhost | localhost |
-NrgAddresses | A comma-separated list of addresses of all YSoft SafeQ Job Services in the near roaming group. If the YSoft SafeQ Job Service is installed with a standalone Site Server then you have to enter the address (typically IP address, hostname or FQDN) of the server where the YSoft SafeQ Job Service is installed. This argument cannot be empty. NrgAddresses The list must not be surrounded with quotation marks (10.0.10.50,10.0.10.51,10.0.10.52 is correct, "10.0.10.50,10.0.10.51,10.0.10.52" is incorrect). | yes | NONE | 10.0.10.50,10.0.10.51,10.0.10.52 |
-NrgAliases | Comma-separated list of aliases of the YSoft SafeQ Job Services in the near roaming group. They have to be in the same order as Job Services. | no | NONE | red,green,blue |
-SigningCertificatePath | Path to the certificate (with public and private key) which will be used for signing access tokens. Use different from HTTPS certificate. The path must contain also the filename of the certificate. The path can be either absolute or relative. | yes | NONE | YSoft SafeQ Signing Certificate.pfx C:\certificates\YSoft SafeQ Signing Certificate.pfx |
-SigningCertificatePassword | The password that was used during signing certificate generation. | yes | NONE | 123456 |
-HttpsCertificatePath | A certificate that will be used to enable HTTPS. This will enable communication encryption between YSoft SafeQ Client and YSoft SafeQ Job Service (and between multiple YSoft SafeQ Job Services). This certificate will be validated by clients. If the validation in the client fails, the client will not communicate with the server. If the path is not provided, the installer will create a self-signed certificate using which you might need to disable the certificate validation on YSoft SafeQ Clients and other YSoft SafeQ Job Services. It is highly recommended to use a certificate that is trusted by your infrastructure. | no | The installer will create a self-signed certificate. | YSoft SafeQ Job Service.pfx |
-HttpsCertificatePassword | The password that was used during certificate generation. | no | ||
-InfinispanPort | Port of Infinispan's REST interface. | no | ||
-DisableCertificateValidation | Switch which disables YSoft SafeQ Job Service's validation of HTTPS certificates. The extent of the validation is certificate and platform dependent (e.g. macOS requirements). Using this switch will severely decrease security. | no | Certificate validation is enabled by default. | This argument is a switch, you should not pass any values to it. |
-SiteServerHosts | Comma-separated list of IP addresses or hostnames of the server where YSoft SafeQ Job Service is installed. This will be used to update the information in the spooler. The spooler will connect to the first one and if it is not available it will randomly select from the rest. | no | NONE | 10.0.10.53,10.0.10.54 |
-SiteServerAliases | Comma-separated list of aliases of the Site Server hosts. They have to be in the same order as Site Server hosts. | no | NONE | eva,merlin |
-JobServicePorts | Comma-separated list of ports where YSoft SafeQ Job Service listens. They have to be in the same order as Site Server hosts. | no | NONE | 5000 |
-ServerSpoolerPorts | Comma-separated list of ports where YSoft SafeQ Spoolers in Server mode listen. They have to be in the same order as Site Server hosts. | no | NONE | 5002,5002 |
-SecureJMX | Switch which enables secure JMX for YSoft SafeQ Job Service Distributed Layer if supplied. For more information about securing JMX see Configuring password authentication for JMX connections. | no | Certificate validation is enabled by default. | This argument is a switch, you should not pass any values to it. |
-SigningCertificateThumbprint | This argument is for the update procedure (see section Updating with preserved configuration and print jobs). Use it only if you have a certificate in the certificate store to use. It sets local.json – IdentityServerOptions – SigningCertificateOptions – Thumbprint. | no | E82D4BAB8938E72914B9D9CBC14F10400C814767 | |
-HttpsCertificateThumbprint | This argument is for the update procedure (see section Updating with preserved configuration and print jobs). Use it only if you have a certificate in the certificate store to use. It sets local.json – HttpServerOptions – CertificateOptions – Thumbprint. | no | 54BB97D3275AF226520F5509B82573B81963385F | |
-SelfUrlResolutionKind | Argument that configures how Job Service resolves its own URL for the purposes of adding itself to the Address Book. Possible values are "Connection", "Host" and "Static". Used when a Job Service is clustered. For details refer to Configuring YSoft SafeQ Job Service. | no | Uses "Connection" when not set | Static |
-SelfUrlResolutionUrl | When SelfUrlResolutionKind is set to "Static", this configures the URL parameter. | no | NONE | https://job-service.example.com:5000 |
Example of script usage
This is an example of how the script can be called when installing a single server (e.g. with IP 10.0.10.50)
.\install.ps1 -NrgAddresses 10.0.10.50 -SigningCertificatePath "YSoft SafeQ Signing Certificate.pfx" -SigningCertificatePassword 123456
This is an example of how the script can be called when installing server s01 as a cluster member:
.\install.ps1 -NrgAddresses s01.example.com,s02.example.com,s03.example.com -SigningCertificatePath "YSoft SafeQ Signing Certificate.pfx" -SigningCertificatePassword 123456 -SelfUrlResolutionKind Static -SelfUrlResolutionUrl https://s01.example.com
This is an example of how the script can be called when specifying an additional list of Site Server hosts:
.\install.ps1 -NrgAddresses 10.0.10.50 -NrgAliases red,blue -SigningCertificatePath "YSoft SafeQ Signing Certificate.pfx" -SigningCertificatePassword 123456 -SiteServerHosts 10.0.10.51,10.0.10.52 -SiteServerAliases eva,merlin -ServerSpoolerPorts 5000,5001 -JobServicePorts 5003,5004
This is an example of how the script can be called when specifying a static SelfUrlResolution (this Job Service is reachable on https://job-service.example.com):
.\install.ps1 -NrgAddresses 10.0.10.50 -SigningCertificatePath "YSoft SafeQ Signing Certificate.pfx" -SigningCertificatePassword 123456 -SelfUrlResolutionKind Static -SelfUrlResolutionUrl https://job-service.example.com:5000
Uninstallation
To uninstall YSoft SafeQ Job Service from the server run the uninstall.ps1 script that is part of the folder where the YSoft SafeQ Job Service is installed or launch these commands in the Windows Command Prompt ( Win+R > type in "cmd" > press Enter )
sc stop "YSoftSQ-JOB-SERVICE"
sc delete "YSoftSQ-JOB-SERVICE"
sc stop "YSoftSQ-JSDL"
sc delete "YSoftSQ-JSDL"
iisreset /stop
RMDIR "C:\SafeQ6\JobService" /Q /S
iisreset /start
Updating with preserved configuration and data
This section describes how to preserve configuration and data (mostly print jobs) during update of YSoft SafeQ Job Service.
Limitations:
- Update removes cached user sessions. Users will have to log in to YSoft SafeQ Client v3 GUI again. This is one time operation which can be mitigated by using single sign-On.
Skipping the cache backup and restore will result in:
- Print jobs spooled before update cannot be released. User may see them on terminal but release attempt will result in error. Solution is to delete such jobs e.g. via Management Interface and user needs to send them for print again.
- Print jobs marked for deletion may remain present in the print job storage (on servers or user workstations). Solution is to delete old jobs manually.
Remarks on backup_ispn.ps1 and restore_ispn.ps1 scripts:
- they are attached within the installation zip package
- use backup_ispn.ps1 from the installation package of Build you are updating FROM
- use restore_ispn.ps1 from the installation package of Build you are updating TO
- if updating from/to Build 75 or older, contact Y Soft support to provide suitable backup_ispn.ps1 (reference SBT-4297)
Performance consideration:
- guids.txt with 100 000 lines will take about 15 minutes to complete the backup and the similar time to do the restore.
- It is possible to save the time and skip the Job Service cache backup/restore, but only if the risks described above are acceptable (print jobs lost, print jobs left on the disk).
- If you decide to skip the cache backup/recovery:
- SQL
-- run this SQL query on SQDB6 database before updating Site Servers -- if you run the query after the update of Site Servers, it is necessary to delete SPOC caches -- query marks all the print jobs as deleted (including favorite jobs), preventing errors upon attempt user to release them update tenant_1.smartq_jobs set cur_status = 32768 where cur_status in (1,2,4,8,16,32,64,128,256,512,1024,131072,131073,131074) and spooler_type='JOB_SERVICE'
Both backup_ispn.ps1 and restore_ispn.ps1 scripts are prepared for the default configuration of the distribution layer. In case you have some custom configuration, you will have to modify backup_ispn.ps1 and restore_ispn.ps1 scripts accordingly as well.
- Stop YSoft SafeQ Job Service (YSoftSQ-JOB-SERVICE) on all Site Servers.
Run this SQL query on SQDB6:
SQLselect job_guid from tenant_1.smartq_jobs where spooler_type='JOB_SERVICE'
Save the output of this query as guids.txt.
- On all Site Servers:
- Copy guids.txt to C:\temp\.
Run backup_ispn.ps1 to make the cache backup. This script creates ispn_backup.json.
Ignore the 404 errors, some jobs might have been already deleted.
Update YSoft SafeQ Job Services on all Site Servers.
- Back up the following configuration folders and files (if they exist):
- <jobservice>\configuration
- <jobservice>\distServer\distServer.conf
- <jobservice>\distServer\jmxremote.access
- <jobservice>\distServer\jmxremote.password
- Uninstall YSoft SafeQ Job Service.
- Install the new version of YSoft SafeQ Job Service with the SigningCertificateThumbprint and HttpsCertificateThumbprint arguments.
- Provide the thumbprint values from the backed-up configuration\local.json configuration file.
- Stop YSoft SafeQ Job Service (YSoftSQ-JOB-SERVICE).
Merge the backed-up configuration folders and files from step a. with the new folders and files created during the installation of a new version.
Individual versions of YSoft SafeQ Job Service can have different configuration options, thus the backed-up configuration has to be merged with the new configuration options accordingly.
One of the common configuration options to be replaced with the backed-up configuration is “Guid” from JobServiceOptions in local.json.
Example of configuration\local.json
CODE"JobServiceOptions": { "DisableCertificateValidation": false, "Guid": "2e8992f4-e57f-4380-b4c6-8adfc854de9e" }
Other options such as SpocAddress and NrgAddresses in configuration\local.json and distServer\distServer.conf depends on whether it was set correctly during the installation of the new version.
If updating from Build 79 or older, make this change in restored config file
distServer\distServer.conf
TEXTremove: ### Type of communication protocol. Keep TCP. ysoft.cluster.protocol=TCP add: ### Enables JGroups diagnostic probing ysoft.jgroups.diag.enabled=false ### The minimum number of threads to use. ysoft.jgroups.thread_pool.min_threads=0 ### The maximum number of threads to use. ysoft.jgroups.thread_pool.max_threads=200
- Back up the following configuration folders and files (if they exist):
- Compare ispn_backup.json files from all Site Servers and pick the one with the biggest data set – just in case the cache was not updated on every server – and then run restore_ispn.ps1 script only on this one particular server.
- Start YSoft SafeQ Job Service (YSoftSQ-JOB-SERVICE) on all Site Servers.
Troubleshooting
Problem
During cache backup using backup_ispn.ps1 or restore_ispn.ps1 there is error:
Invoke-WebRequest : Invalid request path
Resolution
Check that you are using backup_ispn.ps1 or restore_ispn.ps1 script corresponding to the actual version you are backing up from or restoring to.