libcups 3.0.0 release.

Author: michaelrsweet

libcups/client.conf.html

@@ -144,6 +144,26 @@ <h2 id="cups-oauth-1.synopsis">Synopsis</h2>
 [
 <strong>-a</strong>
 <em>OAUTH-URI</em>
+] [
+<strong>-s</strong>
+<em>SCOPE(S)</em>
+]
+<strong>get-device-grant</strong>
+<em>[RESOURCE]</em>
+<br>
+<strong>cups-oauth</strong>
+[
+<strong>-a</strong>
+<em>OAUTH-URI</em>
+]
+<strong>get-device-token</strong>
+<em>[RESOURCE]</em>
+<em>DEVICE-CODE</em>
+<br>
+<strong>cups-oauth</strong>
+[
+<strong>-a</strong>
+<em>OAUTH-URI</em>
 ]
 <strong>get-metadata</strong>
 <em>[NAME]</em>
@@ -196,36 +216,46 @@ <h2 id="cups-oauth-1.options">Options</h2>
 </p>
     <p style="margin-left: 2.5em; text-indent: -2.5em;"><strong>-s </strong><em>SCOPE(S)</em><br>
 Specifies a space-delimited list of scope names to use when authorizing access.
-The default is to request authorization for all supported scopes.
+The default is to request authorization for all supported OpenID scopes.
 </p>
-    <h2 id="cups-oauth-1.commands">Commands</h2>
-    <h3 id="cups-oauth-1.commands.authorize">Authorize</h3>
-<p>Starts an authorization workflow with the default web browser.
+    <h2 id="cups-oauth-1.sub-commands">Sub-Commands</h2>
+    <p style="margin-left: 2.5em; text-indent: -2.5em;"><strong>authorize</strong> [<em>RESOURCE</em>]<br>
+Starts an authorization workflow with the default web browser.
 If a resource URI is specified, the authorization is specific to that resource.
 The access token is send to the standard output on success.
 </p>
-    <h3 id="cups-oauth-1.commands.clear">Clear</h3>
-<p>Clears any authorization for the specified resource or for all resources if no resource URI is supplied.
+    <p style="margin-left: 2.5em; text-indent: -2.5em;"><strong>clear</strong> [<em>RESOURCE</em>]<br>
+Clears any authorization for the specified resource or for all resources if no resource URI is supplied.
+</p>
+    <p style="margin-left: 2.5em; text-indent: -2.5em;"><strong>get-access-token</strong> [<em>RESOURCE</em>]<br>
+Output the current, unexpired access token, if any, to the standard output.
+</p>
+    <p style="margin-left: 2.5em; text-indent: -2.5em;"><strong>get-client-id</strong><br>
+Output the client ID string, if any, to the standard output.
 </p>
-    <h3 id="cups-oauth-1.commands.get-access-token">Get-Access-Token</h3>
-<p>Output the current, unexpired access token, if any, to the standard output.
+    <p style="margin-left: 2.5em; text-indent: -2.5em;"><strong>get-device-grant</strong> [<em>RESOURCE</em>]<br>
+Gets a device authorization grant and outputs the device code, user code, and web page to the standard output.
 </p>
-    <h3 id="cups-oauth-1.commands.get-client-id">Get-Client-Id</h3>
-<p>Output the client ID string, if any, to the standard output.
+    <p style="margin-left: 2.5em; text-indent: -2.5em;"><strong>get-device-token</strong> [<em>RESOURCE</em>] <em>DEVICE-CODE</em><br>
+Waits for device authorization to complete and outputs the device access token to the standard output.
 </p>
-    <h3 id="cups-oauth-1.commands.get-metadata">Get-Metadata</h3>
-<p>Get the OAuth/OpenID authorization server metadata and send it to the standard output.
-If a name is specified, the output is just the value for the specified metadata.
+    <p style="margin-left: 2.5em; text-indent: -2.5em;"><strong>get-metadata</strong> [<em>NAME</em>]<br>
+Get the OAuth/OpenID authorization server metadata and send it to the standard output.
+If
+<em>NAME</em>
+is specified, the output is just the value for the named metadata.
 </p>
-    <h3 id="cups-oauth-1.commands.get-user-id">Get-User-Id</h3>
-<p>Get the OpenID user ID information and send it to the standard output.
-If a name is specified, the output is just the named claim from the user ID.
+    <p style="margin-left: 2.5em; text-indent: -2.5em;"><strong>get-user-id</strong> [<em>RESOURCE</em>] [<em>NAME</em>]<br>
+Get the OpenID user ID information and send it to the standard output.
+If
+<em>NAME</em>
+is specified, the output is just the named claim from the user ID.
 </p>
-    <h3 id="cups-oauth-1.commands.set-access-token">Set-Access-Token</h3>
-<p>Set the access token (which is sometimes also called an API key) for the specified resource or for all resources.
+    <p style="margin-left: 2.5em; text-indent: -2.5em;"><strong>set-access-token</strong> [<em>RESOURCE</em>] <em>TOKEN</em><br>
+Set the access token (which is sometimes also called an API key) for the specified resource or for all resources.
 </p>
-    <h3 id="cups-oauth-1.commands.set-client-data">Set-Client-Data</h3>
-<p>Set the client ID string and secret for an OAuth/OpenID authorization server.
+    <p style="margin-left: 2.5em; text-indent: -2.5em;"><strong>set-client-data</strong> <em>CLIENT-ID</em> <em>CLIENT-SECRET</em><br>
+Set the client ID string and secret for an OAuth/OpenID authorization server.
 </p>
     <h2 id="cups-oauth-1.environment-variables">Environment Variables</h2>
 <p>The
@@ -240,8 +270,18 @@ <h2 id="cups-oauth-1.notes">Notes</h2>
 <p>CUPS uses a redirect URI of &quot;<a href="http://127.0.0.1/&quot;">http://127.0.0.1/&quot;</a> for all authorization on the local system.
 </p>
     <h2 id="cups-oauth-1.examples">Examples</h2>
-<p>TBD
+<p>Register a client ID and secret for the OAuth server at &quot;<a href="https://oauth.example.com/&quot;:">https://oauth.example.com/&quot;:</a>
+</p>
+    <pre>     cups-oauth -a <a href="https://oauth.example.com/">https://oauth.example.com/</a> set-client-data CLIENT-ID CLIENT-SECRET
+</pre>
+<p>Save an access token (sometimes called an application or API key) for the OAuth server at &quot;<a href="https://oauth.example.com/&quot;:">https://oauth.example.com/&quot;:</a>
+</p>
+    <pre>     cups-oauth -a <a href="https://oauth.example.com/">https://oauth.example.com/</a> set-access-token TOKEN
+</pre>
+<p>Authorize against the OAuth server at &quot;<a href="https://oauth.example.com/&quot;">https://oauth.example.com/&quot;</a> using your web browser:
 </p>
+    <pre>     cups-oauth -a <a href="https://oauth.example.com/">https://oauth.example.com/</a> authorize
+</pre>
     <h2 id="cups-oauth-1.see-also">See Also</h2>
 <p><strong>cups</strong>(1)
 

libcups/cups-oauth.html

@@ -97,7 +97,7 @@
   <body>
     <h1 id="cups-x509-1">cups-x509(1)</h1>
     <h2 id="cups-x509-1.name">Name</h2>
-<p>cups-x509 - description
+<p>cups-x509 - manage x.509 certificates and certificate requests
 </p>
     <h2 id="cups-x509-1.synopsis">Synopsis</h2>
 <p><strong>cups-x509</strong>
@@ -148,7 +148,7 @@ <h2 id="cups-x509-1.synopsis">Synopsis</h2>
 <strong>-u</strong>
 <em>USAGE</em>
 ]
-<em>COMMAND</em>
+<em>SUB-COMMAND</em>
 <em>[ARGUMENT(S)]</em>
 </p>
     <h2 id="cups-x509-1.description">Description</h2>
@@ -214,32 +214,52 @@ <h2 id="cups-x509-1.options">Options</h2>
 The supported uses are &quot;digitalSignature&quot;, &quot;nonRepudiation&quot;, &quot;keyEncipherment&quot;, &quot;dataEncipherment&quot;, &quot;keyAgreement&quot;, &quot;keyCertSign&quot;, &quot;cRLSign&quot;, &quot;encipherOnly&quot;, and  &quot;decipherOnly&quot;.
 The preset &quot;default-ca&quot; specifies those uses required for a Certificate Authority, and the preset &quot;default-tls&quot; specifies those uses required for TLS.
 </p>
-    <h2 id="cups-x509-1.commands">Commands</h2>
-    <h3 id="cups-x509-1.commands.ca-common-name">Ca Common-Name</h3>
-<p>Sign a certificate request for the specified common name.
+    <h2 id="cups-x509-1.sub-commands">Sub-Commands</h2>
+    <p style="margin-left: 2.5em; text-indent: -2.5em;"><strong>ca </strong><em>COMMON-NAME</em><br>
+Sign a certificate request for the specified common name.
 </p>
-    <h3 id="cups-x509-1.commands.cacert-common-name">Cacert Common-Name</h3>
-<p>Create a CA certificate for the specified common name.
+    <p style="margin-left: 2.5em; text-indent: -2.5em;"><strong>cacert </strong><em>COMMON-NAME</em><br>
+Create a CA certificate for the specified common name.
 </p>
-    <h3 id="cups-x509-1.commands.cert-common-name">Cert Common-Name</h3>
-<p>Create a certificate for the specified common name.
+    <p style="margin-left: 2.5em; text-indent: -2.5em;"><strong>cert </strong><em>COMMON-NAME</em><br>
+Create a certificate for the specified common name.
 </p>
-    <h3 id="cups-x509-1.commands.client-uri">Client Uri</h3>
-<p>Connect to the specified URI and validate the server's certificate.
+    <p style="margin-left: 2.5em; text-indent: -2.5em;"><strong>client </strong><em>URI</em><br>
+Connect to the specified URI and validate the server's certificate.
 </p>
-    <h3 id="cups-x509-1.commands.csr-common-name">Csr Common-Name</h3>
-<p>Create a certificate signing request for the specified common name.
+    <p style="margin-left: 2.5em; text-indent: -2.5em;"><strong>csr </strong><em>COMMON-NAME</em><br>
+Create a certificate signing request for the specified common name.
 </p>
-    <h3 id="cups-x509-1.commands.server-common-nameport">Server Common-Name[:Port]</h3>
-<p>Run a HTTPS test server that echos back the resource path for every GET request.
-If PORT is not specified, uses a port number from 8000 to 8999.
+    <p style="margin-left: 2.5em; text-indent: -2.5em;"><strong>install </strong><em>COMMON-NAME FILENAME.crt</em> [<em>FILENAME.key</em>]<br>
+Installs a certificate and optional private key for the specified common name.
+The certificate and private key are PEM-encoded files.
 </p>
-    <h3 id="cups-x509-1.commands.show-common-name">Show Common-Name</h3>
-<p>Shows any stored credentials for the specified common name.
+    <p style="margin-left: 2.5em; text-indent: -2.5em;"><strong>server </strong><em>COMMON-NAME</em>[<strong>:</strong><em>PORT</em>]<br>
+Run a HTTPS test server that echos back the resource path for every GET request.
+If
+<em>PORT</em>
+is not specified, uses a port number from 8000 to 8999.
+</p>
+    <p style="margin-left: 2.5em; text-indent: -2.5em;"><strong>show </strong><em>COMMON-NAME</em><br>
+Shows any stored credentials for the specified common name.
 </p>
     <h2 id="cups-x509-1.examples">Examples</h2>
-<p>TBD
+<p>Create a certificate signing request for a 384-bit ECDSA certificate for &quot;server.example.com&quot;:
+</p>
+    <pre>     cups-x509 csr -t ecdsa-p384 server.example.com
+</pre>
+<p>Install the certificate you get back from the CA for &quot;server.example.com&quot;:
+</p>
+    <pre>     cups-x509 install server.example.com server.example.com.crt
+</pre>
+<p>Run a test server for &quot;server.example.com&quot; on port 8080:
+</p>
+    <pre>     cups-x509 server server.example.com:8080
+</pre>
+<p>Test a HTTPS client connection to &quot;www.example.com&quot; with validation:
 </p>
+    <pre>     cups-x509 client --require-ca <a href="https://www.example.com/">https://www.example.com/</a>
+</pre>
     <h2 id="cups-x509-1.see-also">See Also</h2>
 <p><strong>cups</strong>(1)
 

libcups/cups-x509.html

@@ -12,22 +12,22 @@ <h1 class="center"><img src="cups.png" width="64" height="64" alt="CUPS"><br>
 
     <h2>Man Pages</h2>
     <ul>
-      <li>client.conf(5) - client configuration file for cups: <a href="client.conf.html">HTML</a></li>
+      <li>client.conf(5) -  Client Configuration File for CUPS: <a href="client.conf.html">HTML</a></li>
       <li>cups-oauth(1) - Interact with an OAuth/OpenID Authorization Server: <a href="cups-oauth.html">HTML</a></li>
       <li>cups-x509(1) - Manage X.509 Certificates and Certificate Requests: <a href="cups-x509.html">HTML</a></li>
       <li>ippeveprinter(1) - An IPP Everywhere Printer Application for CUPS: <a href="ippeveprinter.html">HTML</a></li>
       <li>ippfind(1) - Find Internet Printing Protocol Printers: <a href="ippfind.html">HTML</a></li>
       <li>ipptool(1) - Perform Internet Printing Protocol Requests: <a href="ipptool.html">HTML</a></li>
       <li>ipptoolfile(5) - ipptool File Format: <a href="ipptoolfile.html">HTML</a></li>
       <li>ipptransform(1) - Convert Document Data to Alternate Formats: <a href="ipptransform.html">HTML</a></li>
+      <li>libcups(3) - CUPS API Library: <a href="libcups.html">HTML</a></li>
     </ul>
 
     <h2>Developer Documentation</h2>
     <ul>
       <li>CUPS Implementation of IPP: <a href="spec-ipp.html">HTML</a></li>
-      <li>CUPS Programming Manual: <a href="cupspm.html">HTML</a> &middot; <a href="cupspm.epub">EPUB</a></li>
+      <li>CUPS Programming Manual: <a href="cupspm3.html">HTML</a> &middot; <a href="cupspm3.epub">EPUB</a></li>
       <li>CUPS Raster Format: <a href="spec-raster.html">HTML</a></li>
-      <li>libcups(3) - CUPS API Library: <a href="libcups.html">HTML</a></li>
     </ul>
   </body>
 </html>

libcups/index.html

@@ -128,10 +128,10 @@ <h2 id="ippeveprinter-1.synopsis">Synopsis</h2>
 <em>DEVICE-URI</em>
 ] [
 <strong>-f</strong>
-<em>TYPE/SUBTYPE[,...]</em>
+<em>INPUT-TYPE/SUBTYPE[,...]</em>
 ] [
 <strong>-F</strong>
-<em>TYPE/SUBTYPE</em>
+<em>OUTPUT-TYPE/SUBTYPE</em>
 ] [
 <strong>-i</strong>
 <em>ICONFILE.png[,...]</em>
@@ -144,6 +144,9 @@ <h2 id="ippeveprinter-1.synopsis">Synopsis</h2>
 <strong>-l</strong>
 <em>LOCATION</em>
 ] [
+<strong>-L</strong>
+<em>LOGFILE</em>
+] [
 <strong>-m</strong>
 <em>MODEL</em>
 ] [
@@ -186,9 +189,11 @@ <h2 id="ippeveprinter-1.options">Options</h2>
     <p style="margin-left: 2.5em; text-indent: -2.5em;"><strong>--no-web-forms</strong><br>
 Disable the web interface forms used to update the media and supply levels.
 </p>
-    <p style="margin-left: 2.5em; text-indent: -2.5em;"><strong>--pam-service </strong><em>service</em><br>
+    <p style="margin-left: 2.5em; text-indent: -2.5em;"><strong>--pam-service </strong><em>SERVICE</em><br>
 Set the PAM service name.
-The default service is &quot;cups&quot;.
+The default service is
+<em>cups</em>.
+
 </p>
     <p style="margin-left: 2.5em; text-indent: -2.5em;"><strong>--version</strong><br>
 Show the CUPS version.
@@ -210,27 +215,31 @@ <h2 id="ippeveprinter-1.options">Options</h2>
 <strong>ippeveprinter</strong>
 uses PAM to authenticate HTTP Basic credentials.
 </p>
-    <p style="margin-left: 2.5em; text-indent: -2.5em;"><strong>-c </strong><em>command</em><br>
+    <p style="margin-left: 2.5em; text-indent: -2.5em;"><strong>-c </strong><em>COMMAND</em><br>
 Run the specified command for each document that is printed.
 </p>
-    <p style="margin-left: 2.5em; text-indent: -2.5em;"><strong>-d </strong><em>spool-directory</em><br>
+    <p style="margin-left: 2.5em; text-indent: -2.5em;"><strong>-d </strong><em>SPOOL-DIRECTORY</em><br>
 Specifies the directory that will hold the print files.
 The default is a directory under the user's current temporary directory.
 </p>
     <p style="margin-left: 2.5em; text-indent: -2.5em;"><strong>-D </strong><em>DEVICE-URI</em><br>
 Set the device URI for print output.
-The URI can be a filename, directory, or a network socket URI of the form &quot;socket://ADDRESS[:PORT]&quot; (where the default port number is 9100).
+The URI can be a filename, directory, or a network socket URI of the form <em>socket://ADDRESS</em>[:<em>PORT</em>] where the default port number is 9100.
 When specifying a directory,
 <strong>ippeveprinter</strong>
 will create an output file using the job ID and name.
 </p>
-    <p style="margin-left: 2.5em; text-indent: -2.5em;"><strong>-f </strong><em>TYPE/SUBTYPE[,...]</em><br>
+    <p style="margin-left: 2.5em; text-indent: -2.5em;"><strong>-f </strong><em>INPUT-TYPE/SUBTYPE[,...]</em><br>
 Specifies a list of MIME media types that the server will accept.
 The default depends on the type of printer created.
 </p>
-    <p style="margin-left: 2.5em; text-indent: -2.5em;"><strong>-F </strong><em>output-type/subtype[,...]</em><br>
+    <p style="margin-left: 2.5em; text-indent: -2.5em;"><strong>-F </strong><em>OUTPUT-TYPE/SUBTYPE[,...]</em><br>
 Specifies the output MIME media type.
-The default is &quot;application/postscript&quot; when the <strong>-P</strong> option is specified.
+The default is
+<em>application/postscript</em>
+when the
+<strong>-P</strong>
+option is specified.
 </p>
     <p style="margin-left: 2.5em; text-indent: -2.5em;"><strong>-i </strong><em>ICONFILE.png[,...]</em><br>
 Specifies the printer icon file for the server.
@@ -239,18 +248,30 @@ <h2 id="ippeveprinter-1.options">Options</h2>
 </p>
     <p style="margin-left: 2.5em; text-indent: -2.5em;"><strong>-k</strong><br>
 Keeps the print documents in the spool directory rather than deleting them.
+</p>
+    <p style="margin-left: 2.5em; text-indent: -2.5em;"><strong>-K </strong><em>KEYSTORE</em><br>
+Specifies the location of X.509 certificates.
 </p>
     <p style="margin-left: 2.5em; text-indent: -2.5em;"><strong>-l </strong><em>LOCATION</em><br>
 Specifies the human-readable location string that is reported by the server.
 The default is the empty string.
+</p>
+    <p style="margin-left: 2.5em; text-indent: -2.5em;"><strong>-L </strong><em>LOGFILE</em><br>
+Specifies the file that is used for log messages.
+If the filename starts with a plus (&quot;+&quot;), log messages are appended to the specified file.
+The default is to send log messages to the standard error.
 </p>
     <p style="margin-left: 2.5em; text-indent: -2.5em;"><strong>-m </strong><em>MODEL</em><br>
 Specifies the model name of the printer.
-The default is &quot;Printer&quot;.
+The default is
+<em>Printer</em>.
+
 </p>
     <p style="margin-left: 2.5em; text-indent: -2.5em;"><strong>-M </strong><em>MANUFACTURER</em><br>
 Set the manufacturer of the printer.
-The default is &quot;Example&quot;.
+The default is
+<em>Example</em>.
+
 </p>
     <p style="margin-left: 2.5em; text-indent: -2.5em;"><strong>-n </strong><em>HOSTNAME</em><br>
 Specifies the hostname that is reported by the server.
@@ -259,7 +280,7 @@ <h2 id="ippeveprinter-1.options">Options</h2>
 
 command.
 </p>
-    <p style="margin-left: 2.5em; text-indent: -2.5em;"><strong>-p </strong><em>PORt</em><br>
+    <p style="margin-left: 2.5em; text-indent: -2.5em;"><strong>-p </strong><em>PORT</em><br>
 Specifies the port number to listen on.
 The default is a user-specific number from 8000 to 8999.
 </p>
@@ -269,12 +290,16 @@ <h2 id="ippeveprinter-1.options">Options</h2>
     <p style="margin-left: 2.5em; text-indent: -2.5em;"><strong>-r </strong><em>SUBTYPE[,...]</em><br>
 Specifies the DNS-SD subtype(s) to advertise.
 Separate multiple subtypes with a comma.
-The default is &quot;_print&quot;.
+The default is
+<em>_print</em>.
+
 </p>
     <p style="margin-left: 2.5em; text-indent: -2.5em;"><strong>-s </strong><em>SPEED[,COLOR-SPEED]</em><br>
 Specifies the printer speed in pages per minute.
 If two numbers are specified and the second number is greater than zero, the server will report support for color printing.
-The default is &quot;10,0&quot;.
+The default is
+<em>10,0</em>.
+
 </p>
     <p style="margin-left: 2.5em; text-indent: -2.5em;"><strong>-S </strong><em>FILENAME.strings</em><br>
 Specifies a strings file for localization.
@@ -286,7 +311,8 @@ <h2 id="ippeveprinter-1.options">Options</h2>
 </p>
     <p style="margin-left: 2.5em; text-indent: -2.5em;"><strong>-V 2.0</strong><br>
 Specifies the maximum IPP version to report.
-2.0 is the default.
+<strong>2.0</strong>
+is the default.
 </p>
     <h2 id="ippeveprinter-1.exit-status">Exit Status</h2>
 <p>The
@@ -306,7 +332,7 @@ <h2 id="ippeveprinter-1.environment">Environment</h2>
 adds environment variables starting with &quot;IPP_&quot; for all IPP Job attributes in the print request.
 For example, when executing a command for an IPP Job containing the &quot;media&quot; Job Template attribute, the &quot;IPP_MEDIA&quot; environment variable will be set to the value of that attribute.
 </p>
-    <p>In addition, all IPP &quot;xxx-default&quot; and &quot;pwg-xxx&quot; Printer Description attributes are added to the environment.
+    <p>In addition, all IPP &quot;xxx-default&quot;, &quot;xxx-ready&quot;, and &quot;xxx-supported&quot; Printer Description attributes are added to the environment.
 For example, the &quot;IPP_MEDIA_DEFAULT&quot; environment variable will be set to the default value for the &quot;media&quot; Job Template attribute.
 </p>
     <p>Enumerated values are converted to their keyword equivalents.
@@ -374,6 +400,6 @@ <h2 id="ippeveprinter-1.see-also">See Also</h2>
 PWG Internet Printing Protocol Workgroup (<a href="http://www.pwg.org/ipp">http://www.pwg.org/ipp</a>)
 </p>
     <h2 id="ippeveprinter-1.copyright">Copyright</h2>
-<p>Copyright &copy; 2021-2023 by OpenPrinting.
+<p>Copyright &copy; 2021-2026 by OpenPrinting.
   </body>
 </html>