FlexiSpooler local configuration through spooler.config file
All configuration options in spooler.config file are case insensitive. That means it does not matter if there is "Authenticationtype": "PIN", or "authenticationtype": "PIN", or "AUTHENTICATIONtype": "PIN". True/false values are also case insensitive.
It is recommended to follow these steps when a change in the spooler.config is needed:
Stop YSoft SafeQ FlexiSpooler service and then stop the process YSoft SafeQ Desktop Interface.
Change the <install_dir>\FSP \Service\spooler.config file.
Start YSoft SafeQ FlexiSpooler service and then YSoft SafeQ Desktop Interface (<install_dir>\FSP \Service\<Spooler 6.0.X.Y>\DesktopInterface\DesktopInterface.exe).
FlexiSpooler configuration options fall into 2 categories:
Global options
These options are expected to be the same for all FlexiSpoolers and are set centrally through YSoft SafeQ management interface to avoid having to configure them for each FlexiSpooler. These options are described in the Management Interface and will not be explained in detail here.
Some of these options (where it makes sense and does not create potential for abuse, most of them are for receiving jobs) can be overridden locally through spooler.config, these options can be used to configure a specific FlexiSpooler differently:
automaticUpdatesEnabled
authenticationType (from version MU6)
billing-codes-enabled
billingCodesSyncCronRule
cacheCredentials
defaultFlexiSpoolerNetworkAddress
defaultPaperSize
deviceUpdate
deviceUpdateIntervalMinutes
directPrintRetryAttempts
directPrintRetryTimeoutSeconds
diskSpaceCheckIntervalInSeconds
dsCertificateFileSource
dsCertificateSource
dsCertificateStore
dsCertificateStoreIdentifier
dumpMemoryOnCrash
fspHttpsSecurityProtocols (from version MU12)
ignoreIppsMfdCertificateErrors (from version MU28)
internalLdapReplaceAtChar
jobAnalysisResolution
jobReplication
legacyClientEnabled (from version MU10)
legacyClientPort (from version MU10)
logPerformanceMetrics (from version MU28)
lprEncoding
lprPrinterConnectionTimeout
lprPrinterConnectionLingerTimeout
maximumOfflinePrinters
maxParallelJobProcessing
minimumDiskSpaceRequired
minimumDiskSpaceRequiredToResumeReception
notificationWindowTimeoutSeconds
numberOfRetriesInCommunication (from version MU13 HFX)
offlinePrintEnabled
ParserPJLUser
parseUserFromJob
parseUserFromTitle
parseUserFromTitleDelimiter
parseUserFromTitleIndex
parseUserFromTitlePreserverTitle
previewResolution
rawPrinterConnectionLingerTimeout
removeInvalidCharactersFromJobTitle
removePjlDminfoForHp (from version MU14)
replicationSharedFolder
replicationSharedFolderCredentials
secureHttp
securePrintDeliveryTimeoutSeconds
secureQueueDisplayName
spoolerCleanerSchedule
SQLPRPrt
uiLaunchAttemptTimeoutSeconds
uiLaunchAttempts
usernameFormat
whoamiLocation
Turning on HTTPS and server authentication can be done via YSoft SafeQ configuration (the options are described in the YSoft SafeQ management interface), but all these values are overwridable locally:
secureHttp for turning https on/off (true/false), supported protocols are listed in fspHttpsSecurityProtocols (new parameter from MU12) For further details see Configuring cryptographic protocols for outbound communication and SSL/TLS Secure Channel - SCHANNEL - Troubleshooting.
dsCertificateSource, dsCertificateStore, dsCertificateStoreIdentifier and dsCertificateFileSource for supplying certificate for server FlexiSpooler authentication.
Local options
These options are set per FlexiSpooler via the local spooler.config file (a JSON file located in the FlexiSpooler installation folder). They are only local because they are not expected to be changed and use the default value unless in rare circumstances, because there is no reasonable global value for all FlexiSpoolers, or because FlexiSpooler needs to know them to even connect to a Spooler Controller and download global YSoft SafeQ configuration. Most of these options have a default value that is used when none is specified in the file. They can be grouped into several main areas:
General options
Local Option Name | Type | Default Value | Description |
configurationUpdateInterval | TimeSpan | 0:15:0 | The interval in which FlexiSpooler checks for changes in YSoft SafeQ configuration, every 15 minutes by default. |
UpdateLocations | boolean | true | By default, FlexiSpooler dynamically updates locations with the latest information from Spooler Controller/FlexiSpooler that it is connected to. This way it has the current IP addresses of servers to connect to during location change or failover. Turn this option off if you want to configure locations manually. |
Username | string | This value is used as username for received jobs when "authenticationType" is set to Stored username | |
IsServer | boolean | false | This turns on or off-server mode (see FlexiSpooler Modes). |
PrintDriverName | string | YSoft Printer Driver PCL | Name of the print driver which would be used for creating direct queues |
jobStorePath | string | JobStore | Path to the job store where are incoming jobs saved in case od spooling mode (see FlexiSpooler Modes and Configuration and usage of JobStore ). Path must be in valid JSON format for example: "C:/JobStore/" - note the path cannot contain backward slashes. Default job store can be found here: <install_dir>/FSP/Service/JobStore |
EndUserInterfaceUrlTemplate | string | https://{0}:9443/end-user/ui | Template for the URL of the End User Interface. Use the following placeholders in the template:
Set to the empty string to remove the option to open the End User Interface from the tray icon menu. |
OverrideDeliveryUrlTo | string | If configured, this option overrides the delivery destination for all jobs released by this spooler to all devices in its Spooler Controller Group.
The intended use case for this configuration is routing all print jobs through a print server when they are being released, allowing the print server to do any processing (such as compression) on the jobs. |
Communication with Spooler Controllers and Desktop Interface
This communication is built on TCP and is configured only locally.
Local Option Name | Type | Default Value | Description |
ControllerPort | integer | 5555 | Port number on which FlexiSpooler connects to Spooler Controller When changing the default value, make sure that the sosApiMessagingV2ListenerPort property is configured to the same port on the Spooler Controller side. |
DesktopInterfacePort | integer | 5558 | Port number on which Desktop Interface connects to FlexiSpooler |
SpoolerId | Guid | new Guid | Unique FlexiSpooler identification for Spooler Controllers, it should not change for the entire lifetime of a FlexiSpooler (that is why IP/host cannot be used). If not filled, it will be filled by a new GUID upon the first start of FlexiSpooler. Do not change this option! Spooler Controllers store the SpoolerId in their metadata for each received job, changing it would mean losing access to all jobs previously stored by that FlexiSpooler. |
UiId | string | SpoolerId-ClientUi | Similar as SpoolerId, this is Desktop Interface's static unique identification and is derived from SpoolerId upon the first run, do not change this option! |
ConnectionLostTimeout | TimeSpan | 0:1:0 | FlexiSpooler uses heartbeat to check the availability of its Spooler Controller, if it is unresponsive for the specified time (1 minute by default), FlexiSpooler can react, failover to another Spooler Controller, go to offline print mode, etc. A higher value may be needed for networks with a high latency or for performance reasons. |
uiLaunchCheckInterval | integer | -1 | Desktop Interface must be running in every user's session for the users to be able to submit print jobs. This property activates automatic checking of the presence of Desktop Interface in all user sessions on the workstation and it starts a new instance when it detects a session without Desktop Interface. The checking is disabled by default. The value of the property specifies an interval in minutes and how often the check is executed. |
By default, this communication is plain, no authentication or encryption. These options can be used to set up secure communication (see System communication hardening). Secure communication must either be used on all FlexiSpoolers and Spooler Controllers or none. A FlexiSpooler will not be able to connect to a Spooler Controller if their security settings do not match. These variables are only a local configuration.
Local Option Name | Type | Default Value | Description |
CertificateThumbprint | string | empty string | If left empty, plain communication is used. Otherwise, FlexiSpooler will look for a matching certificate signed by a trusted authority and use it to authenticate itself to Spooler Controllers (and it will negotiate encryption with it). It will also communicate securely with Desktop Interface. The "encryption" (from MU14) variable must also be set. |
encryption (from MU14) | string | Plain | Encryption key lengths : Supported values are (case insensitive):
|
CertificateStore | enum | My | For secure communication, FlexiSpooler needs a certificate to authenticate itself. It looks for it in the Windows certificate store specified by this option (Personal store by default). |
ValidateServerCertificateHost | boolean | true | By default when authenticating a Spooler Controller, FlexiSpooler also checks if one of the IPs/hosts in the Spooler Controller certificate's subject alternate name matches its IP/host. It's not recommended to turn off this option. |
Communication with Mobile Print, Mobile Integration Gateway, DHCP options 9 and between FlexiSpoolers
This communication is built on HTTP and is configured only locally, except for HTTPS and server authentication options. In this communication, FlexiSpooler acts as a HTTP server, and Mobile Print, Mobile Integration Gateway and client FlexiSpoolers act as HTTP clients.
Local Option Name | Type | Default Value | Description |
ListeningOnAddress | string | 0.0.0.0 | Address on which FlexiSpooler listens for HTTP(s) connections. By default, it listens to all IPv4 addresses on the local machine. |
ListeningForJobsOnAddress | string | 0.0.0.0 | Address on which FlexiSpooler listens for LPR connections. By default, it listens to all IPv4 addresses on the local machine. |
SpoolerPort | integer | 5559 | Port number on which FlexiSpooler listens for http(s) connections. |
HttpRequestTimeout | TimeSpan | 0:10:0 | Timeout for HTTP requests, default is 10 minutes. Non-spooling client FlexiSpoolers transfer job data to spooling server FlexiSpoolers via HTTP, which can take a while depending on job size and network speed, if these transfers fail due to timeout, a higher value might be necessary. |
HttpCompression | boolean | true | When true, FlexiSpooler uses GZip to compress its HTTP requests, to transfer jobs faster and save network bandwidth. |
IgnoreCertificateChainError | boolean | true | This allows a self-signed certificate to be used on the server FlexiSpooler for HTTPS authentication, if true, the certificate chain is ignored during validation. |
MaxHttpConnections | int | 100 | The limit for outgoing HTTP connections on the client side. |
ServerSpoolerAddresses | array of strings | empty array | This enables failover and virtual IPs for non-spooling servers (see FlexiSpooler Modes). Non-spooling client FlexiSpoolers ask their server FlexiSpooler for addresses of all server FlexiSpoolers, so they can failover when one server is down. Spooling server FlexiSpoolers are always on the same server as Spooler Controllers, so they just return the IPs of their Spooler Controller Group. But a non-spooling server returns only its own IP addresses (the "real" ones from network interfaces). When this option is filled, the non-spooling server returns its value instead. This solves a scenario when the non-spooling server is only accessible through a public virtual IP address different from its real IP(for example a server in Azure cloud). It also gives administrators the option to manually configure a non-spooling server FlexiSpooler cluster for failover. |
HttpAuthenticationMethod | None/AzureActiveDirectory | None | This allows client authentication for https communication via Azure Active Directory(server authentication is done via certificates). To use AAD, more local configuration options are necessary - AzureActiveDirectoryTenant, AzureActiveDirectoryAuthorizationEndpoint, AzureApplicationIdUri and AzureNativeClientId. More details are in FlexiSpooler Server HTTP authentication configuration - Azure AD. |
ServerDiscoveryEnabled | boolean | true | Configuration for DHCP discovery. When true, FlexiSpooler queries the DHCP server for option 9 information. |
Automatic FlexiSpooler Update
Local Option Name | Type | Default Value | Description |
spoolerUpdateCheckIntervalInMinutes | integer | 4 | Intervals in which FlexiSpooler checks for a new version, default is 4 minutes. |
updateServerHttpPort | integer | 443 | Port number on which FlexiSpooler connects to Update Server. |
Desktop Interface Notifications
Local Option Name | Type | Default Value | Description |
culture | string | If set, this forces different culture on Desktop Interface (and localize its string in a different language) than the current culture on that machine. Example "en-US", all codes are here: https://msdn.microsoft.com/en-us/library/ee825488(v=cs.20).aspx | |
processingTimeWithoutNotification | integer | 5000 | When receiving a job, FlexiSpooler needs to process it, if it takes longer than this time(5 seconds by default), Desktop Interface will display a notification to inform the user. |
Authentication methods
Properties authenticationType and cacheCredentials can be set centrally in the YSoft SafeQ management interface in System > Spooler tab, and from version MU6 it can be overridden locally for each FlexiSpooler via spooler.config (but are still mentioned here because the option values are different in spooler.config).
Local Option Name | Type | Default Value | Another Value | Description |
authenticationType | string | DOMAIN_USERNAME | DOMAIN_USERNAME | When set to Domain username, the username of the user logged into the workstation is used. |
USERNAME_AND_PASSWORD | When set to Username and password, the user will be prompted for a username and password. | |||
STORED_USERNAME | When set to Stored username, a username will be retrieved from the configuration file. e.g.:
| |||
USERNAME | When set to Username, the user will be prompted only for a username. | |||
CARD | When set to Card, the user will be prompted to swipe their card. | |||
PIN | When set to PIN, the user will be prompted for a PIN. |
LPR byte counting
When sending jobs from FlexiSpooler to a printer via LPR, FlexiSpooler did not send job size as LPR protocol dictates. Instead, FlexiSpooler have sent a specific value (which is used in Windows printing sub-system for jobs with unknown size). While it works for MFDs, this caused issue when sending print job to Windows LPD service via LPR, which would not correctly accept the job.
FlexiSpooler has locally configurable setting for FlexiSpooler which will enable calculation of the job size through usage of a temporary file on the disk where the print job with modifications is generated, size is calculated and then the data is sent to the printer with correct size submitted via LPR protocol. This setting is turned off by default.
Local Option Name | Type | Default Value | Description |
JobDataDump | string | "JobDataDump" relative to the Service folder of FlexiSpooler, e.g. "C:\SafeQ6\FSP\Service\JobDataDump" | Folder where the temporary files containing print job data ready to be sent to the printer. Filename of these files include job GUID, timestamp and random suffix and these files are locked against access by another process throughout their usage during printing and then immediately deleted. |
CalculateJobSizeBeforeDeliveryTimeoutSeconds | integer | 1200 | Timeout for writing the printed job data to the temporary file. |
CalculateJobSizeBeforeDelivery | boolean | false | Enables job size calculation. Job size calculation is currently supported when sending print jobs to MFP via LPR back-ends. Otherwise the job size calculation (along with the creation of temporary file) is not done. |
If the receiving Windows LPD service is still refusing the job at the end, it may also be necessary to add the following registry value on the receiving server.
[HKEY_LOCAL_MACHINE\SYSTEM\ControlSet001\Services\LPDSVC\Parameters]"SimulatePassThrough"=dword:00000001An example spooler.config file
{"CertificateThumbprint" : "77948B8C50205FB8F1EC1AB32EF4F708A65F5422","encryption": "AES128","CertificateStore" : "My","ConnectionLostTimeout" : "0:0:20","DesktopInterfacePort" : "5559","parseUserFromTitle" : "sykoram","ServerSpoolerAddresses" : [ "10.0.11.146", "127.0.0.1" ],"UserNameDelimiterInJobTitle" : "_","updateLocations": "true","isServer" : "false","EndUserInterfaceUrlTemplate":"http://{0}:9443/end-user/ui","jobStorePath": "C:/JobStore/"}