Configuring YSoft SafeQ Job Service

About

• All configuration related files are located in the configuration folder located in YSoft SafeQ Job Services's root folder.

YSoft SafeQ Job Service Configuration

Group	Key	Sub key	Type	Default value	Description
JobServiceOptions	Guid		string		Identifier of the YSoft SafeQ Job Service.
	DisableCertificateValidation		bool	false	Enables/disable certificate validation for connections initiated by YSoft SafeQ Job Service.
	JobPreviewStoreTimeout		TimeSpan	00:01:00	Time that the job preview will be stored for retrieval.
	DirectQueuesTimeout		TimeSpan	00:01:00	Time that direct queues retrieve from YSoft SafeQ Spooler Controller will be cached
	SelfUrlResolution		SelfUrlResolution		Configures how Job Service resolves its own URL for the purposes of adding itself to the Address Book. See Self URL Resolution.
	ClientOptions		JobServiceClientOptions
		ClientId	string	ysoft_safeq_jobservice	OpenID Connect Client Id that will be used be YSoft SafeQ Job Service to authorize service-to-service requests. Identity provider configured in AuthorityOptions will be used. YSoft SafeQ Job Service will use Client Credentials flow to request token.
		ClientSecret	string		OpenID Connect Client secret that will be used be YSoft SafeQ Job Service to authorize service-to-service requests. Identity provider configured in AuthorityOptions will be used. YSoft SafeQ Job Service will use Client Credentials flow to request token.
		Scope	string	print_session:create jobs:delete commands:create	Scopes requested from the identity provider. The identity provider should have these scopes enabled. The configuration value should not be changed.
HttpServerOptions	Host		string	*	Indicates where will YSoft SafeQ Job Service listen. "localhost" to listen only on localhost, "*" to listen on all interfaces.
	Port		int	5000	Port on which the YSoft SafeQ Job Service will listen.
	Scheme		string	https	Indicates whether YSoft SafeQ Job Service will use HTTPS or HTTP
	CertificateOptions		CertificateConfigurationOptions
		Thumbprint	string		TLS certificate with this thumbprint will be loaded from the store specified in StoreName.
		StoreName	string		Certificate store name where the YSoft SafeQ Job Service will look for the TLS certificate.
		StoreLocation	string		Certificate store location where the YSoft SafeQ Job Service will look for the TLS certificate.
		FilePath	string		Path to the TLS certificate (YSoft SafeQ Job Service prioritises certificate in the store over certificate on file path)
		Password	string		Password for the certificate on the path.
IdentityServerOptions	SigningCertificateOptions		CertificateConfigurationOptions		Same structure as the configuration for TLS certificate. This certificate will be used as a key pair for signing access tokens.
	AccessTokenLifetime		TimeSpan	1.00:00:00 (=1 day)	Lifetime of the access token
	AuthenticationCookieLifetime		TimeSpan	00:01:00	Life time of authentication cookie. If after a successful authentication client makes a subsequent request for authentication they will receive a fresh token without having to input their credentials, given it is within the lifetime of the cookie.
	RefreshTokenLifetime		TimeSpan	1.00:00:00 (=1 day)	Lifetime of the refresh token. This represents after how long the user will have to sign in again in case of inactivity.
JNodeOptions	Host		string	localhost	IP Address of the YSoft SafeQ Spooler Controller.
	Port		int	8111	Port of the YSoft SafeQ Spooler Controller.
SpoolerConnectionOptions	KeepAliveInterval		TimeSpan	00:00:05	Represents how long it takes to take YSoft SafeQ Client v3 as disconnected.
	ClientTimeoutInterval		TimeSpan	00:00:30	Represents the time during which the client(s) (spooler) have to send a message before the server closes connection. The value should always be at least double of the client's (spooler) KeepAliveInterval. Default value is 30 seconds, with default of KeepAliveInterval set to 15 seconds.
SpoolerUpdateOptions	PackageMonitoringInterval		TimeSpan	00:10:00	Interval in which update package folder is monitored for new update packages.
	PackageSigningCertificate		CertificateConfigurationOptions		Same structure as the configuration for TLS certificate. Certificate which has been used to sign the update package.
SpoolerOptions	EnableFeedbackForm		bool	false	Enables feedback form from YSoft SafeQ Client tray icon.
	UserInterfacePort		int	3050	Port for hosting the client web application static files.
	EnableQueueManagementInClient		bool		Enables users to manage their print queues using the client application.
	IdentityProviderUrl		string		Identity provider URL.
SafeQConfigurationOptions Mosaic macros cannot be exported to this format.	AuthenticatedUserMustMatchJobTicketOwner		bool	true	Enables/disables validation where YSoft SafeQ Job Service check if the user who is authenticated matched the user who actually sent the print job (the user which the underlying operating system provided in LPR or IPP).
	AuthenticationType		string	DOMAIN_USERNAME	Specifies the authentication type to use on client. Possible values: DOMAIN_USERNAME, USERNAME_AND_PASSWORD, STORED_USERNAME DOMAIN_USERNAME - The Job Service will try to use Windows Integrated Authentication (SSO) to authenticate the user. If SSO is successful the user will not get the login window. If SSO fails user will be prompted for the credentials. USERNAME_AND_PASSWORD - The user will have to enter the credentials to authenticate. STORED_USERNAME - The Job Service will try to use stored username from client to authenticate the user. If authentication is successful the user will not get the login window. If authentication fails user will be prompted for the credentials. DOMAIN_USERNAME_FROM_CLIENT - Client V3 retrieves the username by calling whoami.exe /UPN and uses this as it would be a STORED_USERNAME. It is convenient when Job Service is in a different domain than Client V3 and other is no trust between those domains. The username is always in UPN format user@domain. This option is only for Windows Client V3. If you use also Client V3 on Mac, the AuthenticationType should be locally overridden. Both STORED_USERNAME and DOMAIN_USERNAME_FROM_CLIENT require additional settings on Job Service: SafeQConfigurationOptions.AuthenticatedUserMustMatchJobTicketOwner set to False, SafeQConfigurationOptions.AllowStoredUsernameFromClient set to True.
	UserNameFormat		string		Specifies the user name format used in the rest of the system. Possible values: DOMAIN_USERNAME, DS_NT4_ACCOUNT_NAME, DS_USER_PRINCIPAL_NAME
	AllowStoredUsernameFromClient		bool	false	Enable client username authentication when the STORED_USERNAME or DOMAIN_USERNAME_FROM_CLIENT authentication methods are used. Security Remark for allowing using of STORED_USERNAME authentication type These are the consideration that Admins should keep in mind when setting 'AllowStoredUsernameFromClient' property to true Every request with existing user name submitted to stored username endpoint will return access token. An attacker could make it look like a job is coming from a different user
	DisableImplicitGrant		bool	false	If set to true and AllowStoredUsernameFromClient set to false ysoft_safeq_client which is using OAuth2 implicit grant would be disabled. Do not set if you are using older version of YSoft SafeQ Client v3.
YmqProxyOptions	Port		int	5555	Port on which the YSoft SafeQ Job Service will connect to the Spooler Controller.
	RequestTimeout		TimeSpan	00:00:05	Initial request timeout for requests to YSoft SafeQ Spooler Controller.
	RequestTimeoutIncreaseFactor		double	1.5	A factor by which the RequestTimeout is increased when the requests to YSoft SafeQ Spooler Controller time out.
	MaxRequestTimeout		TimeSpan	00:02:00	A limit of the RequestTimeout value. When the requests to YSoft SafeQ Spooler Controller time out, the RequestTimeout is being progressively increased by the RequestTimeoutIncreaseFactor value while the MaxRequestTimeout is the cap of this increase so that the RequestTimeout does not go beyond this limit.
	NumberOfRetries		int	5	A number of retries a single request to YSoft SafeQ Spooler Controller can be repeated on failure. (Applicable only to requests that can be retried.)
SiteServerOptions.SiteServers	Host		string		IP Address or hostname of the Site Server.
	Alias		string		Alias as Site Server host.
	JobServicePort		int	5000	Port of Job Service.
	ServerSpoolerPort		int	5002	Ports where YSoft SafeQ Spoolers in Server mode listen
Logging.json (file)
Serilog	MinimumLevel	Default	string	Debug	Sets the minimum log level. Security Remark for logging in VERBOSE level When logging in VERBOSE/TRACE level (value "Verbose") log may contain sensitive data like user names and passwords.

• This contains the configuration of YSoft SafeQ Spooler's logging.
• It is based on Serilog's configuration (see https://github.com/serilog/serilog/wiki/Configuration-Basics).
• Some of the default options
  • path (default 'logs/jobservice.log') – location of the log
  • rollingInterval (default 'Day') – specifies the minimum time when the log will be rotated (this adds the date format to the log file name). Available options are Infinite, Year, Month, Day, Hour, Minute 
  • fileSizeLimitBytes (default 20000000) – maximal size of log file
  • rollOnFileSizeLimit (default true) – specifies if log will be rotated after maximum size is reached, if false, NOTHING is logged when the maximal limit is reached.
  • retainedFileCountLimit (default 30) – maximal number of log files. If exceeded, the oldest file gets deleted
• The configuration archives the logs in a GZip format after file roll.

Self-URL resolution

This configuration is required only when a Job Service is clustered. Spooler keeps an active connection with exactly one Job Service. When a Spooler connects to Job Service, Job Service stores its own URL and the GUID of the Spooler in the address book. The address book is shared in a clustered cache. When the Job Service needs to send a command (e.g. to release print job) to the Spooler it has no direct connection with, it will route the command through the Job Service where the Spooler is connected to. This implies that:

• The URL must be reachable from the other Job Services.
• The URL must point at exactly one Job Service.
• The URL must be unique for each Job Service.
• The URL cannot be an address of the Load Balancer (this would violate condition for uniqueness).
• The URL must align with the TLS certificate of a Job Service if https is used. For example, if the certificate specifies a SAN containing a DNS name (and not an IP address), then URL must contain the name.
• The URL resolution is done whenever Spooler connects.

In a situations with proxies, load balancers, containers and other infrastructure, auto-detecting the right URL may not be possible. This class enables advanced configuration for such an environment.

Configuration is done in the JobServiceOptions:SelfUrlResolution section which has the following properties:

Kind set to Connection

Job Service uses the local IP address and port of the incoming Spooler connection to determine its self-URL. These will most likely be equal to an address of the network interface that the request was received on and the port that the application is listening on. The scheme will be the same as the incoming Spooler connection.

This will always be an IPv4/IPv6 address. With this configuration the IP address must be listed in SAN of Job Service's TLS certificate.

Configuration example

Kind set to Host

Job Service will use the Host header and the scheme of the incoming Spooler connection.

This option is useful when there are multiple Job Services directly behind a load balancer and the load balancer forwards the requests with the Host header changed to the actual host of the Job Service. This option doesn't work properly when there are multiple Job Services behind a load balancer that preserves the Host header of the original request (for example, Apache's mod_proxy with ProxyPreserveHost enabled) as Job Service will assume the address of the load balancer itself.

Security Remark: When using this option, make sure that the Job Service is only reachable from trusted infrastructure (i.e. load balancers and proxies that set their own Host header and from other Job Services), as otherwise an attacker might provide their own Host header.

Configuration example

Example

Spooler connects to https://job-service.example.com. This is address of a load balancer that forwards the request to https://job-service-1.example.com:5000. While forwarding the request it replaces Host header with job-service-1.example.com:5000. The job-service-1.example.com:5000 is an address where the Job Service actually listens at. The resulting self-URL is a construct of the Host header and the protocol.

Kind set to Static

Job Service uses Url from the configuration file as a self-URL. This is mainly useful when securing a communication by Job Service's TLS certificate with SAN containing FQDN (but not containing IP address).
In the most common deployment scenario the port in Url should match the value of HttpServerOptions.Port from the same configuration file.
Setting up a non-local address/port can be helpful in case a port forwarding or another complex routing between Job Services is used (that means when the server is reachable on a different address/port from outside than where it listens locally).

Configuration example

Notes

Mosaic macros cannot be exported to this format.