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
| ||
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
{ |
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 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
{ |