cupsctl

Display the current configuration values

$ cupsctl

$ cupsctl -h [server[:port]]

$ cupsctl -E

$ cupsctl [--debug-logging|--no-debug-logging]

$ cupsctl [--remote-admin|--no-remote-admin]

$ cupsctl | grep '^_debug_logging' | awk -F= '{print $2}'

cupsctl [ OPTIONS ] [ SETTING=VALUE ... ]
cupsctl [ --help | --version ]

-E
    Forces encryption (HTTPS) when connecting to the CUPS server.

-U username
    Specifies the username to use for authentication with the server.

-P
    Prompts the user for a password when connecting to the server.

-h hostname[:port]
    Specifies an alternate CUPS server to connect to. The default is localhost:631.

--debug
    Enables debugging output during command execution, providing more verbose information about the process.

--no-daemon
    Prevents cupsctl from automatically restarting the cupsd daemon after configuration changes are applied. Changes will not take effect until the daemon is manually restarted.

--[no-]remote-admin
    Enables (--remote-admin) or disables (--no-remote-admin) remote administration of the CUPS server via its web interface. Enabling this allows other machines to access the administration pages.

--[no-]remote-printers
    Enables (--remote-printers) or disables (--no-remote-printers) remote printer browsing/sharing for printers served by this CUPS instance. This affects whether printers on this server are advertised to other CUPS servers.

--[no-]share-printers
    Enables (--share-printers) or disables (--no-share-printers) sharing of local printers via IPP, LPD, and SMB protocols. This makes local printers available to other computers on the network.

--[no-]web-interface
    Enables (--web-interface) or disables (--no-web-interface) the CUPS web-based administration interface, typically accessed at http://localhost:631.

--[no-]user-interface
    Deprecated in newer CUPS versions, this option previously controlled the user interface (often synonymous with --web-interface). It should generally be avoided in favor of --web-interface.

--[no-]private-browsing
    Enables (--private-browsing) or disables (--no-private-browsing) private browsing mode for CUPS, which can affect the visibility of network printers and job history for users.

SETTING=VALUE
    Sets a specific configuration directive in the cupsd.conf file to the provided value. For example, LogLevel=debug to increase logging detail, or Port=80 to change the listening port. Multiple settings can be specified.

--help
    Displays a brief help message with command usage and available options, then exits.

--version
    Displays the CUPS version information that cupsctl is part of, then exits.

cupsctl is a command-line utility used to query, display, and change the operational settings of the Common Unix Printing System (CUPS) scheduler daemon, cupsd. It provides a convenient way for administrators to manage the global configuration of the CUPS server, which is typically stored in the cupsd.conf file. Changes made with cupsctl are persistent, meaning they are written directly to the configuration file, and the CUPS daemon is usually restarted to apply them immediately. This command is essential for tasks like enabling or disabling the CUPS web interface, managing remote administration access, setting log levels, and configuring printer sharing options without directly editing the configuration file.

Most operations with cupsctl that modify settings require administrative privileges (typically root or a user in the 'lpadmin' group, depending on your system's CUPS configuration). Incorrectly configuring CUPS settings can lead to service disruptions, printing failures, or security vulnerabilities. Enabling remote administration or sharing options should be done with extreme caution, especially in insecure or untrusted network environments, as it can expose your printing system to unauthorized access.

A key feature of cupsctl is that changes made using this command are permanently written to the main CUPS configuration file, cupsd.conf. This ensures that your server settings persist across daemon restarts and system reboots, unlike some other utilities that might apply temporary configurations.

By default, after successfully applying configuration changes, cupsctl attempts to gracefully restart the cupsd daemon. This action ensures that the new settings take effect immediately without requiring manual intervention. If this automatic restart behavior is not desired (e.g., when scripting multiple changes), the --no-daemon option can be used to suppress it.

cupsctl is an integral component of the Common Unix Printing System (CUPS), which was originally developed by Easy Software Products and later acquired by Apple Inc. in 2007. Since its inception, CUPS has aimed to provide a modular, standardized, and extensible printing system for Unix-like operating systems. cupsctl has been a core utility for managing the runtime configuration of the cupsd daemon, abstracting the direct editing of cupsd.conf and ensuring proper interaction with the running service. Its functionality has remained largely consistent throughout CUPS's development, serving as the primary command-line interface for global server settings.

cupsd(8), cupsd.conf(5), lpadmin(8), lpstat(1), cancel(1), enable(1), disable(1)