In this two part article series by Ankur Shah, we will learn how to monitor CUPS using the lpstat command, and also study about access_log and the error_log files in the first part. And in the second part, we will also see how Simple Network Management Protocol (SNMP) helps CUPS discover the printer and help other networking tools such as Cacti in managing printers.

The Common UNIX Printing System (CUPS) is actually a printer management tool, and thus monitoring CUPS always remains a very essential activity to to make the best use of the resources available. Monitoring CUPS will allow us to take action quickly should something go wrong.

Using the lpstat Command

The lpstat command displays the status of the CUPS service, printers, classes, and jobs. It supports a number of options. If the command is used without any options, it displays the job queues for the current user:

$lpstat
cupstest-3 kajol 8192 Tue Aug 05 13:24:43 2008
cupstest-4 kajol 8192 Tue Aug 05 13:25:34 2008

To check whether the CUPS server is running, use the -r option.

$lpstat -r
scheduler is running
$lpstat -d
system default destination: cupsclass

The above command gives information about the default destination printer or class. The output following the command shows that the default destination of the system is cupsclass.

$lpstat -c cupsclass

This shows the printer class and the member printers belonging to that class. If a particular class is not specified, then the output shows all classes along with their member printers.

members of class cupsclass:
cupsprinter1
cupsprinter2
$lpstat -v cupsprinter2

The command above will show the device to which cupsprinter1 is attached. If no printers are specified, then the output will list all printers along with device-uri information.

device for cupsprinter2: ipp://cupsserver.cupsgroup.org/printers/cupsprinter2
$lpstat -s

This shows a status summary for all printers and classes on the network. The summary includes the default destination, a list of classes and their member printers, and a list of printers and their associated devices. The output is equivalent to using the -d, -c, and -v options simultaneously.

system default destination: cupsclass
members of class cupsclass:
cupsprinter1
cupsprinter2
device for cupsprinter1: lpd://192.168.0.11/printers/cupsprinter1
device for cupsprinter2: ipp://cupsserver.cupsgroup.org/printers/cupsprinter2
$lpstat -a

This command shows if printers are currently accepting jobs. If no printers are specified, then it will list all printers.

cupsprinter1 accepting requests since Mon 16 Jun 2008 02:28:14 PM IST
cupsprinter2 accepting requests since Wed 18 Jun 2008 11:07:23 AM IST
$lpstat -p cupsprinter1

This shows whether the printer cupsprinter1 is enabled and if it is currently printing a job. If no printers are specified then all the printers are listed.

printer cupsprinter1 is idle. enabled since Mon 16 Jun 2008 02:28:14 PM IST
$lpstat -o

This shows the job queues on the specified destinations. If no destinations are specified then all jobs are shown.

$lpstat -t

This displays status information for all printers, which is equivalent to using the -r, -d, -c, -v, -a, -p, and -o options.

scheduler is running
system default destination: cupsclass
members of class cupsclass:
cupsprinter1
cupsprinter2
device for cupsprinter1: lpd://192.168.0.11/printers/cupsprinter1
device for cupsprinter2: ipp://cupsserver.cupsgroup.org/printers/cupsprinter2
cupsprinter1 accepting requests since Mon 16 Jun 2008 02:28:14 PM IST
cupsprinter2 accepting requests since Wed 18 Jun 2008 11:07:23 AM IST
printer cupsprinter1 is idle. enabled since Mon 16 Jun 2008 02:28:14 PM IST
printer cupsprinter2 now printing cupsprinter2-5711. enabled since Wed 18 Jun 2008 03:12:55 PM IST
Printer is now on-line.
cupsprinter2-5711 kajol 1449984 Wed 18 Jun 2008 03:12:55 PM IST
$lpstat -l

This command displays printers, classes, or jobs in a long list.

$lpstat -u

This shows a list of print jobs queued by the specified users. If no users are specified, it lists the jobs queued by the current user.

cupsprinter2-5711 kajol 1449984 Wed 18 Jun 2008 03:12:55 PM IST
$lpstat -h 192.168.0.11:631

The above command specifies an alternative server for CUPS. It uses the port number that is specified along with the server. If no port is specified, then it will connect to the default port 631.

$lpstat -U username

You can specify an alternative username with the -U option

$lpstat -R : $lpstat -W all

This shows the ranking of print jobs.

This command specifies which jobs to show, complete, incomplete (the default), or all. This option must appear before the -o option and any printer names:

$lpstat -W completed -o cupsprinter2

The output will be as follows

cupsprinter2-5709 kajol 483328 Wed 18 Jun 2008 03:10:45 PM IST
cupsprinter2-5710 kajol 97280 Wed 18 Jun 2008 03:12:18 PM IST
cupsprinter2-5711 kajol 1449984 Wed 18 Jun 2008 03:12:55 PM IST
cupsprinter2-5712 kajol 8192 Wed 18 Jun 2008 03:22:31 PM IST
cupsprinter2-5713 kajol 9216 Wed 18 Jun 2008 03:23:38 PM IST
cupsprinter2-5714 kajol 9216 Wed 18 Jun 2008 03:24:23 PM IST
$lpstat -E

This command forces encryption when connecting to a print server.

Overview of the access_log File

The access_log file lists each HTTP resource that is accessed by a web browser or a CUPS/IPP client. The file contains the lines specified in the following log format, which is an extension of the Common Log Format used by many web servers and web reporting tools.

The "Common Log Format" is a standardized text file format used by web servers while generating log files. As the format is standardized, the files may be analyzed by a variety of analysis programs.

The syntax of the access_log file is :

host group user date-time "method resource version"
status bytes iPP-operations ipp-status

• Hostname: The host field contains the IP address or hostname that can be seen if the "HostNameLookups" directive is enabled in the cupsd.conf file.
• Groupname: The value always remains "-" for the group field.
• Username: The user field is the authenticated username of the requesting user. If no authenticated username is supplied for the request, then this field contains "-".
• Time of printing: The date-time field refers to the date and time of the request in local time. Here, the "local time" denotes the time of the print server.
• Method: The method field is the HTTP method used (GET,OPTIONS,PUT,POST, and so forth).
1. GET: These requests are used to get files from the server, both for the web interface and for the configuration and log files.
2. OPTIONS: These requests are used to upgrade connections to TLS encryption.
3. PUT: These requests are used to upload the configuration files.
4. POST: These requests are used for web interface forms and IPP requests.
• Resource: The resource field records the filename of the requested resource.
• Version: The version field is the HTTP specification version used by the client. The value is always "HTTP/1.1" for CUPS clients.
• Status: The status gives the HTTP result status of the request. Usually, the status code is 200, which suggests an OK status. If the code is 401, then it suggests Unauthorized Access. The following are some of the Status Codes along with their meaning:
1. 200: This status code denotes successful operation, which means OK status.
2. 201: This denotes that a file has been created or modified successfully.
3. 304: The code 304 suggests that the requested file has not changed.
4. 400: This means Bad HTTP request, as in some malicious program is trying to access your server.
5. 401: The code 401 means there has been an attempt at Unauthorized Access. The correct login information (username + password) is required to authenticate.
6. 403: This code refers to Access is forbidden, which means that a client tried to access a resource or file for which they did not have permission.
7. 404: The code 404 denotes that the requested file or resource does not exist.
8. 405: This code means the URL access method is not allowed. It means a web browser is using the server as a proxy.
9. 413: This means that the request is too large. It occurs when the client tries to print a file larger than the MaxRequestSize allows.
10. 426: A server may indicate that a client request cannot be completed without TLS using the Upgrade Required status code, which must include an upgrade header field specifying the token of the required TLS version
11. 500: This code denotes that there is a server error. The log for the error can be checked in the server's error_log file.
12. 501: The client has requested encryption, but the encryption support is not enabled on the server.
13. 505: The given HTTP version number is not supported, which normally happens when some malicious program is trying to access your server.
14. You can get more information about these status codes at: http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html
• Size in bytes: The bytes field contains the number of bytes in the request. For POST requests, the bytes field contains the number of bytes that were received from the client.
<
• IPP Operations: The ipp-operation field denotes the the name of the CUPS-IPP operation that performed the POST request. The value for the description of CUPS-IPP operation is given here:
  

• IPP status: The ipp-status field denotes the IPP-status code name for the POST requests. The value for this field will be "-" for non-IPP requests. With each IPP operation, a number of IPP statuses are possible. The default information can be found at the following URL:
  http://www.cups.org/documentation.php/spec-ipp.html
  Here are the example lines from an access_log file:

192.168.0.35 - - [18/Jun/2008:10:46:37 +0530]
"GET
/admin HTTP/1.1" 401 0 - -
192.168.0.33 - -
[18/Jun/2008:10:38:30 +0530]
"POST
/printers/cupsprinter1HTTP/1.1"
200 130 Get-Printer-Attributes
successful-ok
localhost - - [18/Jun/2008:10:36:38 +0530] "POST
/ HTTP/1.1"
200 182 CUPS-Get-Printers
successful-ok
192.168.5.19 - - [05/Jun/2008:17:46:04
+0530]
"POST /printers/ HTTP/1.1" 200
159656
Print-Job
client-error-document-format-not-supported

Overview of the error_log File

The error_log file displays messages from the scheduler such as "warnings", "errors", and so on:

• Level: The level field contains the type of message:
  A: Alert message (LogLevel alert)
  C: Critical error message (LogLevel crit)
  D: Debugging message (LogLevel debug)
  d: Detailed debugging message (LogLevel debug2)
  E: Normal error message (LogLevel error)
  I: Informational message (LogLevel info)
  N: Notice message (LogLevel notice)
  W: Warning message (LogLevel warn)
  X: Emergency error message (LogLevel emerg)
• Time of Printing: The date-time field contains the date and time when the page started printing. The format of this field is identical to the data-time field in the page_log file.
• Message: This field contains free-form textual messages. In the following examples of the error_log files, the last field contains messages of this type.

The syntax for the error_log file is level date-time message.

The following are the some examples of entries in the error_log file :

I [05/Jun/2008:15:23:46 +0530] Job 224 queued on 'cupsprinter' by 'hritik'.
I [05/Jun/2008:15:23:46 +0530] Job 304 was cancelled by 'aamir'.
D [18/Jun/2008:14:53:18 +0530] cupsdProcessIPPRequest: 12 status_code=0 (successful-ok)
I [05/Jun/2008:15:23:46 +0530] Job 309 queued on 'cupsprnter' by 'kajol'.
I [05/Jun/2008:15:23:46 +0530] Job 322 queued on 'cupsprinter' by 'kajol'.

How SNMP Helps Search for Network Printers

Most of the network printers that CUPS uses, use one of these three TCP/IP-based protocols:

• AppSocket
• Internet Printing Protocol (IPP)
• Line Printer Daemon (LPD)

Now apart from these protocols, CUPS also uses another networking protocol—SNMP that is used to search for networked printers. In future, CUPS will support other networking protocols such as multicast DNS service for the same purpose. First, we will discuss how the configuration of SNMP is done within CUPS (/etc/cups/snmp.conf), and then we will check how it actually works in the web interface. Before we start discussing the snmp.conf file, let us see the some of the key terms related to the file.

The SNMP stands for "Simple Network Management Protocol" and consists of three key components:

• Managed Devices: A managed device is a node that has an SNMP agent, and resides on a managed network. These devices can be routers and access servers, switches, bridges, hubs, computer hosts, or printers.
• Agents: An agent is a software module residing within a device. This agent translates information into a format compatible with SNMP
• Network-Management Systems (NMS): An NMS runs monitoring applications, which provide the bulk of processing and memory resources required for network management.

Overview of snmp.conf

Since CUPS is a printer management system working on networking protocols, SNMP will be an integral part of the CUPS system. The configuration file snmp.conf resides in /etc/cups, and contains various directives, which determine the behavior of the SNMP printer discovery backend. The file contains the directive name followed by its value. The number sign "#" is used to specify the comments.

Currently, the SNMPv1 protocol is being used by the SNMP backend to discover network printers in CUPS and help to determine the correct device URI and the vendor, and the driver of each printer. IT expects that the future release of CUPS will have support for all SNMP versions including, SNMPv2, v2c, and v3.

SNMP actually collects information from the MIB (Management Information Base) host along with port probes to get this information. It is expected that, in future, CUPS will start supporting the new Port monitor MIB as well. The following are some of the key definitions related to MIB.

MIB stands for Management Information Base, which is a collection of information organized hierarchically. It is accessed using a protocol such as SNMP. There are two types of MIBs:

• Scalar: Scalar objects define a single object instance.
• Tabular: Tabular objects define multiple related object instances grouped in MIB tables.

Address

This directive specifies a broadcast address to be used when discovering printers. We can also specify multiple address lines to scan different subnets.

The following examples show various values that can be given along with this directive. The value @LOCAL denotes broadcasting across all LANs. The value @LOCAL is also the default value for this directive, while @IF broadcasts to the named interface. You can also provide the broadcast address or the IP address with the directive for which broadcasting needs to be done.

Address @LOCAL
Address @IF(name)
Address 255.255.255.255
Address 192.168.0.255

Community

The directive Community is used to specify a community name that can be used while discovering printers. The default value for this directive is public. You can specify multiple lines to scan different SNMP communities.

Community public
Community cupsgrp
Community packtpub

DebugLevel

The DebugLevel directive denotes the specified debugging level to be used when searching for network printers. This directive can have four debugging levels. It starts from 0 and ends with 3:

DebugLevel 0
DebugLevel 1
DebugLevel 2
DebugLevel 3

In the above example:

Level 0: It is used to disable debugging, and hence does not produce any debugging information. It is also the default level of debugging.

Level 1: It generates basic debugging information.

Level 2: It also prints the SNMP messages along with the basic debugging information.

Level 3: This level adds a hexadecimal code dump of the network data.

DeviceURI

The directive DeviceURI is used to specify a regular expression, which is enclosed in double quotes. This URI is checked with the SNMP device description OID returned by a printer.

OID stands for Object Identifier. These uniquely identify the objects managed in the MIB hierarchy. This hierarchy can be depicted as a tree, the levels of which are assigned by different organizations.

If the given description matches the regular expression, the CUPS backend will list each of the device URIs that follow by regular expression.

The following are some examples that show DeviceURI directives along with the regular expression and the actual device URI.

Please note that here any occurrence of %s is replaced by the device's IP address or hostname. Here xx, yyy, and zzzz are a part of the regular expressions. We can use the make and model of the printer for these.

If no URIs are listed within this directive, then the requested device will be ignored. These directives are processed serially in the order specified in the snmp.conf file, until a match is found. The following are some of the examples of the directive:

DeviceURI "xx.*" socket://%s
DeviceURI "*LaseJet.*" socket://%s:9100 socket://%s:9101
DeviceURI "yyy.*"
DeviceURI "zzzz.*Desk.*" lpd://%s/printer

HostNameLookups

This directive is used to specify whether the printer addresses are converted to hostnames, or remain as numeric IP addresses. The default value for this directive is off.

HostNameLookups off
HostNameLookups on

MaxRunTime

The MaxRunTime directive specifies the maximum time (in seconds) spent by the SNMP backend searching for printers across the network. As the following example shows, it can contain any integer value. The default value for this directive is 10 seconds.

MaxRunTime 10
MaxRunTime 480

Summary

In this article, we have covered the usage of lpstat Command. We also learnt about snmp.conf in detail, got an overview of the access_log file and error_log file.

If you have read this article you may be interested to view :

• CUPS: How to Manage Multiple Printers
• Monitoring CUPS- part2

A practical tutorial to installing, managing, and securing this powerful printing system Install and configure the CUPS server and set up clients Manage Printers through the command line and web interface and manage users Monitor the CUPS server along with filtering and file typing Secure your CUPS server http://www.packtpub.com/printing-with-cups-common-unix-printing-system/book

About the Author

Ankur Shah has been working with Linux/AIX for last 4 years as a System Administrator. His previous assignment was with Packt Publishing, where he worked as System Administrator and also started implementing CUPS. He completed his graduation in Computer Engineering from Nagpur University, India. He is currently working as a SAP Basis Administrator and also started working on Governance Risk and Compliance for access Control. He is also interested in Oracle Database Administration and Security.

He is the biggest fan of Kajol (a Bollywood actress) and dedicates this book to her. The day her movie releases is a day of celebration for him and he only parties once a year - 5th August - that's Kajol's birthday. It goes without saying that he watches all her movies several times - often dragging his friends and family to participate in his madness.