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:

  1. Stop YSoft SafeQ FlexiSpooler service and then stop the process YSoft SafeQ Desktop Interface.

  2. Change the <install_dir>\FSP \Service\spooler.config file.

  3. 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:

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:

  • {0} for the IP address of the currently connected Spooler Controller,

  • {1} for the GUID of the current FlexiSpooler,

  • {2} for the current user's username.

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.

  • If set to "ipp://<ip>:<port>/<path>/", jobs will be delivered by IPP to <ip> on port <port> with URL /<path>/<queue>, where <queue> is the queue name configured for the device in YSoft SafeQ in the Back-end section. The actual back-end configured for the device, or its IP address, will not be used.

  • If set to "ipps://<ip>:<port>/<path>/", jobs will be delivered by IPP/SSL to <ip> on port <port> with URL /<path>/<queue>.

  • If set to "lpr://<ip>:<port>/", jobs will be delivered by LPR to <ip> on port <port> with queue name <queue>.

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):

  • Plain

  • Aes128

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.
Value can be overwritten in spooler.config file, to disable it set "ServerDiscoveryEnabled": "False". For disabling it in the silent installer use parameter /CFG:noServerDiscovery.

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.:

  • spooler.config - "username":"admin"

  • Management database - usernameFormat = "Plain username"

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:00000001

An 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/"
}