13.5. Advanced Configuration

The majority of SavaPage configuration is conducted in the Administrator Web App. Additional configuration options can be set in the /opt/savapage/server/server.properties configuration file, and with the Config Editor.

13.5.1. Alternative TCP/IP Settings

13.5.1.1. Alternative TCP/IP Ports

Alternative port are set in the /opt/savapage/server/server.properties configuration file as shown in the table below.

KeyDescription

server.port

Server http port. Default: 8631

server.ssl.port

Server https port. Default: 8632

server.html.redirect.ssl

Redirect HTML of non-SSL port to SSL: true or false (default). This only concerns HTML, IPP traffic is not redirected.

server.print.port.raw

The RAW Print Server port. Default: 9100

  • Value 0: RAW printing is disabled.

Table 13.5. Server Properties: Alternative TCP/IP Ports


Important

Since SavaPage is run by user savapage, you can't use ports below 1024, because these ports can only be bound to by the superuser (root). If you want SavaPage Web Apps to be accessible through port 80 and 443 at all costs, you can use Apache or NGINX server to forward (or "reverse-proxy") requests to SavaPage.

13.5.1.2. Server ThreadPool Settings

A high reliability server process like SavaPage must reject excess requests immediately (fail fast) by using a Request Queue with a bounded capacity.

When a request is rejected, the user browser will show a diagnostic message, for example that The connection to the server was reset while the page was loading because The site could be temporarily unavailable or too busy, with the advise to Try again in a few moments.

Rejected request in Firefox browser

Figure 13.1. Rejected request in Firefox browser


Request Queue capacity is calculated according to a tolerable no-response time.

For example, if the server is capable of handling 100 requests per second, and 30 seconds of patience is accepted by users in the event of excessive high load, you can set the queue capacity to 30*100=3000.

If queue capacity is set too low, the server will reject requests too soon and won't be able to handle normal load spikes. If set too high, a high load, that exceeds the processing power of the server application, will continue to stack requests on the queue. And thus, even after the load stops, the application will appear to have stopped responding to new requests as it still has lots of requests on the queue to handle.

Requests are FIFO processed by threads contained in a ThreadPool. The maximum number of threads needed, in order to achieve the best performance, depends on host resources (RAM and CPU cores) assigned to the SavaPage application. The maximum value will typically be between 50 and 500.

The keys to set thread pool and queue capacity in the /opt/savapage/server/server.properties configuration file are shown in the table below.

KeyDescription

server.threadpool.queue.capacity

The capacity (maximum length) of the queue holding client requests to the server. Requests are FIFO processed by threads in the pool. Default: 3000

server.threadpool.maxthreads

Maximum number of threads in the pool. Default: 200

server.threadpool.minthreads

Minimum number of threads in the pool. Default: 20

server.threadpool.idle-timeout-msec

Maximum time a thread may be idle in milliseconds after it is terminated. Default: 30000

Table 13.6. Server Properties: ThreadPool Settings


ThreadPool settings are part of application performance tuning. See Chapter 22, Tuning in general and Section 22.1, “Linux Kernel Parameters” in particular.

Note

The browser connection reset message can be easily provoked by setting very low threadpool values, like:

server.threadpool.queue.capacity=4
server.threadpool.minthreads=1
server.threadpool.maxthreads=5
server.threadpool.idle-timeout-msec=10000

... and frantically pressing the F5 browser key.

13.5.1.3. Server Session Settings

Server Web Sessions expire after a certain period of inactivity: see Section 17.3.1, “Web Session Timeout”. Expired sessions are removed by a cyclic scavenge process. The cycle interval can be set with this property:

KeyDescription

server.session.scavenge.interval-sec

The interval (seconds) at which expired server sessions are scavenged. Default: 600

Table 13.7. Server Properties: Session Settings


13.5.2. HTTP XFF Header Settings

SavaPage uses the Remote IP address from an HTTP Request as Client IP address. This usually works out well. However, when client requests go through an HTTP Proxy or Load Balancer, the Remote IP address will be the IP address of the proxy or load balancer only. In that case the Remote IP address can't be used to define Devices or to restrict access to SavaPage objects, like Queues, Web Services, etc. To solve this issue you can set the properties below to use the HTPP X-Forwarded-For header to retrieve the correct Client IP address.

Configuration propertyDescription

webserver.http.header.xff.enable

Use the X-Forwarded-For (XFF) HTTP header to retrieve Client IP address. Values: N (default) | Y. If Y, the HTPP "X-Forwarded-For" header is used to retrieve the Client IP address.

webserver.http.header.xff.proxies.allowed

A CIDR Set of allowed XFF proxies. If empty all proxies are allowed. Default: empty.

webserver.http.header.xff.debug

Enable X-Forwarded-For (XFF) HTTP header debugging. Values: N (default) | Y. If Y, INFO messages are send to the Admin Dashboard for each retrieved Client IP address.

Table 13.8. HTTP Configuration Properties


See Section 4.11.14, “Config Editor” on how to set these properties.

13.5.3. Database Connection Settings

Database connections are both expensive to create and maintain over time. Therefore, they are an ideal resource to pool. That is just what SavaPage does, with the help of JDBC Connection Pooling[28].

The keys to set the Connection parameters in the /opt/savapage/server/server.properties configuration file are shown in the table below.

KeyDescription

database.connection.pool.max

Maximum number of connections in the pool. Default: 200

Important: if you are using PostgreSQL as database back-end this value must align with the maximum number of client connections allowed by the database. See Section 13.5.3.1, “PostgreSQL Settings”.

database.connection.pool.min

Minimum number of connections in the pool. Default: 5

database.connection.idle-timeout-secs

Maximum time a connection may be idle in seconds after it is closed. Default: 600

database.connection.idle-timeout-test-secs

Idle time in seconds before a connection is checked for timeout. Default: 120

This value must be less than database.connection.idle-timeout-secs. If not, connections closed by the database will not be detected.

database.connection.statement-cache

Number of prepared SQL statements that will be cached. Default: 50

Value 0 disables caching.

Table 13.9. Database Connection Settings


Note

Database Connection Settings do not apply to the internal database.

13.5.3.1. PostgreSQL Settings

PostgreSQL ships with a basic configuration tuned for wide compatibility rather than performance. Depending on available host resources and Database Connection Settings as described in the section above, there is a good chance the default parameters are very undersized.

Tuning Your PostgreSQL Server is an expert job, but there are two obvious parameters in postgresql.conf[29] you need to consider:

  1. max_connections must at least be equal to database.connection.pool.max plus the value of superuser_reserved_connections. For example:

    #----------------------------------------------------------------
    # When SavaPage: database.connection.pool.max = 200
    # and in this file: superuser_reserved_connections = 3
    # and SavaPage is the only process accessing the Database ...
    #----------------------------------------------------------------
    max_connections = 203    # (change requires restart)
    
    # Defaults to 3
    #superuser_reserved_connections = 3

    See PostgreSQL Connection Settings.

  2. The shared_buffers default of 128MB can be replaced by a higher value, depending on the total RAM in your system. For example:

    #----------------------------------------------------------------
    # System has 16GB RAM, we take a conservative 6.25% ...
    #----------------------------------------------------------------
    #shared_buffers = 128MB  # min 128kB 
                             # (change requires restart)
    shared_buffers = 1024MB

    A higher value allocates more shared memory during inter-process communication (IPC) between the database server and the requesting client, resulting in speedier data transfer. See PostgreSQL Memory.

Important: restart the database after changing any of these settings.

13.5.4. CUPS Settings

13.5.4.1. CUPS Notifier

CUPS notifier is a custom SavaPage binary that pushes printer and print job status events from CUPS to SavaPage server. It is the default CUPS notification method. A pull method can be activated as alternative.

Occasionally the notifier may fail to deliver job state notifications, as can be seen reported in /var/log/cups/error_log. Since a failure can result in no job end states being observed, a heartbeat monitor pulls print status from CUPS for active jobs that have not been notified since the previous beat of the heart. The heartbeat period can be configured: see Section 13.5.4.4, “CUPS Configuration Properties”.

13.5.4.2. CUPS Job Status

CUPS Job Status is handled in the following way:

  • Normally a print job that is stopped in CUPS, for instance because job-completed-with-errors, must be manually controlled (reprint, cancel, move) by an operator. However, when SavaPage identifies a stopped job it cancels it automatically.

  • At system (application) start-up, job status is pulled from CUPS for every proxy printed document that has not reached end-state.

See Section 13.5.4.4, “CUPS Configuration Properties” on how to change the defaults.

13.5.4.3. CUPS IPP connections

See Section 13.5.4.4, “CUPS Configuration Properties” on how to change defaults for the number of IPP connections to local CUPS and their IPP connect and read timeouts.

13.5.4.4. CUPS Configuration Properties

Configuration propertyDescription

cups.ipp.notification.method

CUPS event notification method. Value PUSH (default) activates pushed print job status notification by CUPS Notifier. If value is PULL, print job status is pulled from CUPS.

cups.ipp.notification.push.notify-lease-duration

Duration of the subscription lease (seconds) for PUSH notification with the CUPS Notifier. Value must be greater than one (1) hour, since the renewal of the subscription is scheduled by SavaPage every hour. Default: 4200. See Hourly Jobs.

cups.ipp.notification.push.heartbeat-msec

Number of milliseconds to wait before evaluating pushed CUPS job status notifications. Default: 4000.

cups.ipp.notification.push.pull-fallback-msec

Number of milliseconds since the last pushed print job status notification by CUPS Notifier after which a job status update is pulled from CUPS. Default: 30000.

cups.ipp.notification.pull.heartbeat-msec

Number of milliseconds to wait before pulling CUPS job status. Default: 5000.

cups.ipp.job-state.cancel-if-stopped.enable

Set to Y (default) or N, to enable/disable automatic cancellation of stopped CUPS Job Status.

system.startup.cups.ipp.sync-print-jobs.enable

Set to Y (default) or N, to enable/disable CUPS Job Status synchronization at system start-up.

cups.ipp.local-connect-timeout-msec

IPP connect timeout in milliseconds on local CUPS. Default: 5000.

cups.ipp.local-socket-timeout-msec

IPP read timeout in milliseconds on local CUPS. Default: 9000.

cups.ipp.max-connections

Max number of IPP connections on CUPS. Default: 10.

Table 13.10. CUPS Configuration Properties


See Section 4.11.14, “Config Editor” on how to set these properties.

13.5.5. Server-side Download

A Web Page or Document can be printed by a Drag & Drop of its URL. In that case its content is server-side downloaded and rendered as PDF.

Configuration propertyDescription

download.connect-timeout-msec

Timeout in milliseconds until a connection is established. Default: 4000.

download.socket-timeout-msec

Timeout in milliseconds to receive data from remote host after the connection is established, i.e. maximum time of inactivity between two data packets. Default: 2000.

download.max-connections

Max number of download connections. Default: 10.

download.max-connections-per-route

Max number of download connections per route (host) Default: 2.

Table 13.11. Server-side Download Configuration Properties


See Section 4.11.14, “Config Editor” on how to set these properties.

Tip

Rendering a Web Page by a Drag & Drop of its URL gives best results when wkhtmltopdf is installed.

13.5.6. RESTful Client

When SavaPage makes RESTful API calls to third-party servers, for instance in the IPP Routing Plug-in, these are the configuration properties to consider.

Configuration propertyDescription

restful.client.connect-timeout-msec

Timeout in milliseconds until a connection is established. Default: 4000.

restful.client.read-timeout-msec

Timeout in milliseconds to receive data from remote host after the connection is established, i.e. maximum time of inactivity between two data packets. Default: 2000.

restful.client.max-connections

Max number of RESTful client. Default: 100.

restful.client.max-connections-per-route

Max number of RESTful client connections per route (host) Default: 20.

restful.client.trust-self-signed

Trust self-signed certificate of RESTful servers: N (default) or Y.

Table 13.12. RESTful Client Configuration Properties


See Section 4.11.14, “Config Editor” on how to set these properties.

13.5.7. User Home Clean

When Document expiration time is enabled, any SafePages document older than the number of configured minutes is considered expired and will be automatically deleted in an active User Web App session. Moreover, when a user logs out and logs in again, expired documents will be auto-deleted. So, when a user does not log in for a long time, old documents will stay put in the user's home directory. These ignored documents take up unnecessary space. The same applies to PDF documents that exist long after their due date, because their deletion is triggered far too late (never) at Fast Print or Hold Print release.

During Daily Maintenance user home directories are scanned and ignored documents deleted. The result of the scan is shown in the Admin Dashboard. These are the configuration properties to consider:

Configuration propertyDescription

print-in.job-expiry-ignored.mins

Number of minutes added to print-in job expiry (if applicable) after which job is considered ignored. Ignored jobs are removed by Daily Maintenance. Default: 10.

proxy-print.hold-ignored-mins

Number of minutes added to Hold Print job expiry after which job is considered ignored. Ignored jobs are removed by Daily Maintenance. Default: 10.

Table 13.13. User Home Clean Configuration Properties


See Section 4.11.14, “Config Editor” on how to set these properties.

Note

User Home Clean is also executed at server start-up. You can disable this behavior in a separate Server Setting.

13.5.8. Database Locking

When using an External Database, table row locking is used to serialize access to individual user resources. Production grade databases like PostgreSQL should be able to handle row locking without problems. However, if you do suspect problems in this area, please contact SavaPage support. In the meantime, you can disable row locking with the property below.

Configuration propertyDescription

webapp.user.database-user-row-locking.enabled

Enable user table row locking in database to serialize access of a user to database or user home file system: Y (default) | N.

Table 13.14. Database Locking Configuration Properties


See Section 4.11.14, “Config Editor” on how to set these properties.

13.5.9. pdf2cairo Image Strategy

SavaPage uses pdftocairo to create PNG images from SafePages. On centos-release-7-7.1908.0.el7, pdftocairo 0.26.5 fails due to a bug. Therefore pdftocairo -v is executed at server start-up to determine the best way to create images. If version is 0.26.5 is encountered workaround statements are applied. This default probe strategy can be overwritten with this configuration property:

Configuration propertyDescription

system.host.cmd.pdftocairo.img.strategy

Strategy for executing pdftocairo command to create a PNG image. Values: AUTO = use version probe to determine optimal command (default), STREAM = use one (1) stdout/stdin stream command, SPLIT = split action into separate commands.

Table 13.15. pdf2cairo Image Strategy Configuration Property


See Section 4.11.14, “Config Editor” on how to set these properties.

13.5.10. Alternative File Locations

To separate files created at runtime from installation files you can set alternative locations for temporary files, SafePages, public Letterheads and Document Store in the /opt/savapage/server/server.properties configuration file.

Caution

All alternative file locations must reside on the same disk partition[30].

KeyDescription

app.dir.tmp

Location of temporary files created by SavaPage. It is created when the application starts and removed when stopped, so make sure it is exclusively used by the SavaPage application.

The location is not used by third-party Java components: they use java.io.tmpdir to store their own temporary files.

Default: subdirectory savapage of JVM system property java.io.tmpdir. See Section 22.3.3, “JVM Temporary Files”.

  • User savapage must have permission to create the location.

app.dir.safepages

Location where the user's SafePages are stored.

Default: /opt/savapage/server/data/internal/safepages

  • The location directory must be owned by user savapage and have permission 700.

app.dir.letterheads

Location where the public Letterheads are stored.

Default: /opt/savapage/server/data/internal/letterheads

  • The location directory must be owned by user savapage and have permission 700.

app.dir.doc.store.archive

Location where the Archive branch of the Document Store is stored.

Default: /opt/savapage/server/data/doc-archive

  • User savapage must have permission to create the location.

app.dir.doc.store.journal

Location where the Journal branch of the Document Store is stored.

Default: /opt/savapage/server/data/doc-journal

  • User savapage must have permission to create the location.

Table 13.16. Server Properties for Alternative File Locations


13.5.11. Miscellaneous Settings

These are the extra settings that can be configured in the /opt/savapage/server/server.properties configuration file.

KeyDescription

start.cleanup-doclog

Enable database cleanup at server start-up. See Section 4.11.12, “Backups”.

Values: true (default) or false

start.cleanup-userhome

Enable User Home Clean at server start-up.

Values: true (default) or false

system.cleanup-userhome.test

Put User Home Clean in test mode: i.e. cleanable files are signaled on the Admin Dashboard but not deleted.

Values: false (default) or true

visitor.organization

Organization name of Visitor without a Community Member Card. See Section 23.1, “Visitor Period”.

webapp.custom.i18n

See Section 20.1.1.4, “Custom i18n”.

Values: true or false (default).

Table 13.17. Server Properties: Miscellaneous Settings




[28] SavaPage uses Java Database Connectivity (JDBC) Connection Pooling from c3p0: an easy-to-use library for making traditional JDBC drivers enterprise-ready.

[29] On Debian based systems postgresql.conf is located in /etc/postgresql/[version]/main/

[30] This constraint is needed because files are initially created in the temporary location and atomically moved to their destination. Atomic moves do not work cross-partition.