doc/help/spec-browsing.html

   1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
   2 <html>
   3 <!-- SECTION: Specifications -->
   4 <head>
   5         <title>CUPS Browse Protocol</title>
   6         <meta name='keywords' content='Programming'>
   7 </head>
   8 <body>
   9 <!--
  10   "$Id$"
  11
  12   CUPS Browse Protocol specification for the Common UNIX Printing System (CUPS).
  13
  14   Copyright 2008 by Apple Inc.
  15   Copyright 1997-2005 by Easy Software Products.
  16
  17   These coded instructions, statements, and computer programs are the
  18   property of Apple Inc. and are protected by Federal copyright
  19   law.  Distribution and use rights are outlined in the file "LICENSE.txt"
  20   which should have been included with this file.  If this file is
  21   file is missing or damaged, see the license at "http://www.cups.org/".
  22 -->
  23
  24 <h2><a name='INTRO'>Introduction</a></h2>
  25
  26 <p>This specification describes the CUPS browsing protocol which is used for
  27 printer sharing. The protocol is a UDP/IP-based broadcast service that
  28 operates on IP service port 631 by default. Each broadcast packet describes
  29 a single printer or class being shared.</p>
  30
  31 <p>For simple networks with a single subnet, a CUPS system sharing a printer
  32 (the <em>server</em>) will periodically broadcast that printer's availability
  33 and status information to the subnet. Every other CUPS system on the subnet
  34 (the <em>clients</em>) will receive the broadcast and make that printer
  35 available to local users. If a client stops receiving broadcasts from the
  36 server, or if the server sends a special "deleted" broadcast message, the
  37 client will remove its copy of the printer.</p>
  38
  39 <p>For larger networks with multiple subnets, a relay configuration can be used
  40 where one or more client systems poll the server and then broadcast the
  41 availability and status information for the server's shared printers to the
  42 clients' local subnets.</p>
  43
  44 <p>A key feature of CUPS printer sharing is support for <em>implicit
  45 classes</em>, which are automatically-created classes for printers that are
  46 shared by multiple servers. These implicit classes provide automatic load
  47 balancing and fail-safe printing functionality transparently to the user.</p>
  48
  49
  50 <h2><a name='SECURITY'>Security Considerations</a></h2>
  51
  52 <p>Like most discovery protocols, CUPS browse packets are not encrypted or
  53 signed, so it is possible for malicious systems on a network to advertise
  54 or remove printers on that network to cause denial of service or information
  55 disclosure. In order to combat this, CUPS logs incoming browse packets and
  56 provides access controls to limit browse packet reception to known hosts.</p>
  57
  58
  59 <h2><a name='FORMAT'>Browse Packet Format</a></h2>
  60
  61 <p>Each broadcast packet is an ASCII text string of up to 1450 bytes ending
  62 with a line feed (0x0a). The general format is:</p>
  63
  64 <p class='summary'>
  65 printer-type printer-state printer-uri "printer-location" "printer-info"
  66 "printer-make-and-model" name=value name2=value2 ...
  67 </p>
  68
  69 <p>Each of the fields contains the value of the corresponding IPP attribute.
  70 The trailing "name=value" information is used to convey default job template
  71 attribute values (job-sheets-default, media-default, etc.), authentication
  72 requirements (auth-info-required), and additional IPP URI options that are
  73 requested by the server (ipp-options).</p>
  74
  75 <h3>ABNF Definition</h3>
  76
  77 <p>The following ABNF definition [RFC4234, RFC3986] defines the format of each
  78 browse packet:</p>
  79
  80 <pre class='command'>
  81 PACKET         = TYPE WSP STATE WSP URI WSP LOCATION WSP INFO WSP
  82                  MAKE-AND-MODEL WSP *[ WSP ATTR-NAME "=" ATTR-VALUE ] LF
  83
  84 TYPE           = 1*HEXDIG
  85
  86 STATE          = "3" / "4" / "5"
  87
  88 URI            = "ipp://" ( 1*NAMECHAR / IP-literal / IPv4address )
  89                  [ ":" 1*DIGIT ] ( "/printers/" / "/classes/" ) 1*NAMECHAR
  90 NAMECHAR       = %x21.22.24.26-2E.30-7E / %x25 HEXDIG HEXDIG
  91 IP-literal     = See RFC 3986
  92 IPv4address    = See RFC 3986
  93
  94 LOCATION       = QUOTED-STRING
  95 INFO           = QUOTED-STRING
  96 MAKE-AND-MODEL = QUOTED-STRING
  97
  98 ATTR-NAME      = 1*( ALPHA / DIGIT / "-" / "." )
  99 ATTR-VALUE     = QUOTED-STRING / 1*UNQUOTE-CHAR
 100
 101 QUOTED-STRING  = DQUOTE *QUOTED-CHAR DQUOTE
 102 QUOTED-CHAR    = %x20.21.23-5B.5D-7E / UTF8-CHAR / %x5C %x5C / %x5C %x22
 103 UNQUOTE-CHAR   = %x21.23-26.28-5B.5D-7E / UTF8-CHAR
 104 UTF8-CHAR      = %xC0.DF %x80.BF / %xE0.EF %x80.BF %x80.BF /
 105                  %xF0.F7 %x80.BF %x80.BF %x80.BF
 106 </pre>
 107
 108 </body>
 109 </html>