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.

AuthenticationOptions

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: AuthenticationOptions. AuthenticatedUserMustMatchJobTicketOwner set to False, AuthenticationOptions.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

P orts 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:

Key

Sub Key

Possible values

Default value

Example

Description

Kind


Connection, Host, Static

Connection

Static

Specifies which kind of self-URL resolution should be used. See description below.

Static

Url

<url>


https://job-service.example.com

Configures the static self-URL of the Job Service when Kind is Static.

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

{
"JobServiceOptions": {
"SelfUrlResolution": {
"Kind": "Connection"
}
}
}

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

{
"JobServiceOptions": {
"SelfUrlResolution": {
"Kind": "Host"
}
}
}

Example

Spooler connects to https://job-service.example.com. This is a load balancer that forwards the request to https://job-service-1.example.com, thus replacing the Host header with job-service-1.foo.bar. job-service-1.foo.bar is an actual Job Service which constructs its self-URL based on the incoming protocol and the Host header and thus it ends up with https://job-service-1.example.com, which is correct.

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

{
"JobServiceOptions": {
"SelfUrlResolution": {
"Kind": "Static",
"Static": {
"Url": "https://job-service.example.com:5000"
}
}
}
}