.. /* * This file is part of the SavaPage project . * Copyright (c) 2026 Datraverse B.V. * Author: Rijk Ravestein. * * SPDX-FileCopyrightText: (c) 2020 Datraverse B.V. * SPDX-License-Identifier: CC-BY-SA-4.0 * * For more information, please contact Datraverse B.V. at this * address: info@datraverse.com */ .. _ch-install-config-cups-samba: Step 3 - Configure CUPS and Samba --------------------------------- .. contents:: |RST_TABLE_OF_CONTENTS| :depth: 1 :local: .. _ch-install-config-cups-samba-introduction: Introduction ~~~~~~~~~~~~ Make sure to *not* publish shared printers in CUPS *and* Samba. Publishing shared printers creates a loophole by which users can access a printer directly from their workstation and print outside the control of |PRODUCT_NAME|. For Samba, just edit the ``/etc/samba/smb.conf`` file and disable the ``[printers]`` share definition. In CUPS, do *not* enable the “Publish shared printers connected to this system” option as offered in the Print Server Settings dialog. When no such dialog is available you can make the adaption in the CUPS Administrator Web interface (“Share printers connected to this system”), or manually in the ``cupsd.conf`` [1]_ file. .. important:: Before editing ``cupsd.conf`` first stop CUPS by entering this command: .. code-block:: bash sudo systemctl stop cups.service Check if ``cupsd.conf`` contains the snippets below that restrict CUPS to ``localhost`` only. If not, change the configuration file accordingly and leave all other content as it is. .. code-block:: bash :emphasize-lines: 2,5,8,9,10 # Only listen for connections from the local machine. Listen localhost:631 # Disable printer sharing. Browsing Off # Restrict access from localhost only Order allow,deny .. important:: Each individual proxy candidate CUPS printer must be *shared* locally so the ``savapage`` system account can access it. Enabling the shared option can be done in a printer GUI dialog, in the CUPS Administrator Web interface, or directly in the ``printers.conf`` [2]_ file by setting the ``Shared Yes`` option for a printer. .. [1] On Debian, RHEL and openSUSE systems ``cupsd.conf`` is located in the ``/etc/cups/`` directory. .. [2] On Debian, RHEL and openSUSE systems ``printers.conf`` is located in the ``/etc/cups/`` directory. CUPS Remote Printer Browsing ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ To prevent remote printers that DNSSD broadcast themselves, to be discovered by CUPS and synchronized into |PRODUCT_NAME|, edit ``cups-browsed.conf`` [3]_ file, and change it as follows: .. code-block:: text BrowseRemoteProtocols none .. [3] On Debian, RHEL and openSUSE systems ``cups-browsed.conf`` is located in the ``/etc/cups/`` directory. .. _ch-install-config-cups-job-history: CUPS Job History ~~~~~~~~~~~~~~~~ An active SavaPage server captures print job statuses real-time, but when the server is restarted it needs CUPS job history to catch up with the latest statuses. To avoid lost job statuses, CUPS must be told to “Preserve job history”. You can set the Job History option in the Print Server Settings dialog (“Preserve job history but not files”, or optionally “Preserve job history (allow reprinting)”), in the CUPS Administrator Web Interface (Advanced settings, “Retain Metadata : Yes”, and optionally “Retain Documents : Yes”) , or manually by changing the ``cupsd.conf`` file as follows: .. callout:: .. code-block:: conf :emphasize-lines: 2 :caption: cupsd.conf MaxJobs 500 # <1> PreserveJobHistory Yes # <2> PreserveJobFiles No # <2> .. annotations:: :1: ``MaxJobs`` Controls the maximum number of jobs that are kept in memory. Once the number of jobs reaches the limit, the oldest completed job is automatically purged from the system to make room for the new one. If all of the known jobs are still pending or active then the new job will be rejected. The default setting is 500 (in this example this default is explicitly set). Set to ``0`` to allow an unlimited number of jobs. :2: ``PreserveJobHistory`` specifies whether *metadata* is preserved after a job is printed. A value of ``Yes`` will preserve history, a value of ``No`` will not. If a numeric value is specified, history is preserved for the indicated number of seconds after printing. Set to **Yes**. :3: ``PreserveJobFiles`` specifies whether job *files* (documents) are preserved after printing. A value of ``Yes`` will preserve files, a value of ``No`` will not. If a numeric value is specified, files are preserved for the indicated number of seconds after printing. Set this option as you wish, but remember that (spool) files can get big. If you run SavaPage on a host system with limited storage (for instance on a virtual machine) you better set this value to **No**. The number of preserved history jobs can be checked with this command: .. code-block:: bash sudo find /var/spool/cups/ -maxdepth 1 -type f -name 'c*' | wc -l The number of preserved job files can be checked with: .. code-block:: bash sudo find /var/spool/cups/ -maxdepth 1 -type f -name 'p*' | wc -l .. _ch-install-config-cups-job-id: CUPS Job ID ~~~~~~~~~~~ .. contents:: :depth: 1 :local: Background ^^^^^^^^^^ This section gives you some background information about the ID that CUPS assigns to a print job [4]_ . There is nothing you need to configure for this, and you don't really need to consider this info at a first time SavaPage installation. However, do read carefully when |RST_LINK_APPENDIX_MIGRATING|, or if you plan to meddle with CUPS cache. The CUPS Job ID is a global integer that is incremented and assigned to each new print job. In this way, a Job ID refers to a single job within the CUPS cache. When a document is printed from |PRODUCT_NAME|, its Job ID is persisted in the SavaPage database and used to retrieve CUPS job status information, or to link incoming CUPS status notifications to the printed document. When you delete the content of the CUPS cache directory ``/var/cache/cups/``, the Job ID offset is reset to zero. If SavaPage depends on this CUPS instance, the cache will be out-of-sync with the CUPS Job ID range as persisted in the |PRODUCT_NAME| database. This will most likely result in newly issued job ID's that are already present in the SavaPage database, and so introduce a non-unique relation between printed document and CUPS job ID. Also, when SavaPage is moved to another server an out-of-sync is very likely. How does SavaPage deal with the possibility of an out-of-sync situation? 1. For incoming CUPS notifications, the most recent document that matches the provided Job ID, and has not yet reached final state (completed, cancelled, aborted), is updated with the provided status. 2. When retrieval of Job ID status information for a document with non-final state from CUPS fails, then print status is set to “unknown” and time completed to system time. .. [4] CUPS ``NextJobId`` is held in ``/var/cache/cups/job.cache`` .. _ch-install-config-cups-job-id-duplicates: CUPS Job ID Duplicates ^^^^^^^^^^^^^^^^^^^^^^ During intensive proxy printing, a ``MaxJobs`` value that is too low (even the default value of ``500``) may be reached during peak times. This can happen in a Job Ticket scenario where different departments send tickets simultaneously, each for a specific :ref:`Job Ticket Group `. In this case, we have found that sometimes the same Job ID was issued for different print jobs. Although these jobs with duplicate IDs reach the printer and are printed successfully, the completed status is only updated in SavaPage for the most recent document that matches the specified Job ID. As :ref:`explained above `, older documents with the same Job ID are not updated and retain their Active (“pending”) or Unknown status. See :ref:`this section `. .. important:: If you observe this behavior, first set ``MaxJobs`` to a much higher value to prevent future occurrences. Second, in the Admin Web App, as administrator with :ref:`permission to edit accounts `, you can manually simulate a Cancel or Complete for Printed documents with duplicate Job IDs that have the status Active or Unknown. For this you must set :ref:`Configuration property ` ``proxy-print.job-state.edit.enable = Y``. Set the property back to ``N`` after you have made the corrections. See :ref:`Proxy Print Status `. .. _ch-install-config-cups-job-privacy: CUPS Job Privacy ~~~~~~~~~~~~~~~~ CUPS makes “job-name”, “job-originating-host-name” and “job-originating-user-name” private by default. This means that personal data are anonymized in the CUPS Web interface, as shown below. .. figure:: ../images/manual/screenshots/admin/sp-00-install-cups-web-interface-job-privacy.png :alt: CUPS job privacy You can restore the default by changing the ``JobPrivateValues`` directive in the ``cupsd.conf`` file as follows: .. code-block:: text :emphasize-lines: 2 JobPrivateValues default .. _ch-install-config-cups-web-interface: CUPS Web Interface ~~~~~~~~~~~~~~~~~~ If you want to use the CUPS Web Interface for administration from all machines on the local network you should adapt ``cupsd.conf`` as follows: .. code-block:: text :emphasize-lines: 2,5,7,12,17,24 # Allow remote access Port 631 # Disable printer sharing. Browsing Off WebInterface Yes # Allow shared printing... Order allow,deny Allow @LOCAL Order allow,deny Allow @LOCAL AuthType Default Require user @SYSTEM Order allow,deny Allow @LOCAL .. note:: The ``@LOCAL`` name will allow access from all *local* interfaces. This can be confusing since the host system running CUPS often belongs to a different set of subnets from its clients. In that case you can specify multiple ``Allow`` directives, one for each allowed subnet. See the `cupsd.conf man page `__. .. _ch-install-config-cups-security-fix: CUPS security fix ~~~~~~~~~~~~~~~~~ CUPS versions before 2.4.3 contain a security issue that allows users to retrieve documents (pending or printed) without authentication [5]_ . If this CUPS version is installed, modify ``cupsd.conf`` as shown below. .. code-block:: text :emphasize-lines: 4,9 ... ... # Remove the CUPS-Get-Document operation from tag ... Require user @OWNER @SYSTEM Order deny,allow # ... and insert section below AuthType Default Require user @OWNER @SYSTEM Order deny,allow ... ... .. [5] `CVE-2023-32360 `__ An unauthenticated user may be able to access recently printed documents was reported by Gerhard Muth and explained in personal communication with the author of this manual. Also see `About the security content of macOS Ventura 13.4 `__ and `RHSA-2023:4771 - Security Advisory `__. .. _ch-install-config-cups-restart: Test CUPS ~~~~~~~~~ When CUPS was stopped earlier you need to start CUPS again with this command: .. code-block:: bash sudo systemctl start cups.service Now you can test if the CUPS print queues to be used as :ref:`Proxy Printer ` work as expected.