idnits 2.17.1 draft-ietf-svrloc-service-scheme-12.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** Looks like you're using RFC 2026 boilerplate. This must be updated to follow RFC 3978/3979, as updated by RFC 4748. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- ** Missing expiration date. The document expiration date should appear on the first and last page. ** The document seems to lack a 1id_guidelines paragraph about Internet-Drafts being working documents. ** The document seems to lack a 1id_guidelines paragraph about 6 months document validity -- however, there's a paragraph with a matching beginning. Boilerplate error? ** The document seems to lack a 1id_guidelines paragraph about the list of current Internet-Drafts. ** The document seems to lack a 1id_guidelines paragraph about the list of Shadow Directories. == No 'Intended status' indicated for this document; assuming Proposed Standard Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The document seems to lack separate sections for Informative/Normative References. All references will be assumed normative when checking for downward references. ** There are 4 instances of too long lines in the document, the longest one being 2 characters in excess of 72. ** The document seems to lack a both a reference to RFC 2119 and the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords. RFC 2119 keyword, line 50: '... They SHOULD be used by administrati...' RFC 2119 keyword, line 180: '...en the service type name SHOULD either...' RFC 2119 keyword, line 246: '...the service: URL MUST conform to an 'a...' RFC 2119 keyword, line 429: '...egistering agent SHOULD also keep trac...' RFC 2119 keyword, line 506: '...act service-type SHOULD be used. The ...' (14 more instances...) Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the RFC 3978 Section 5.4 Copyright Line does not match the current year == Line 1476 has weird spacing: '...sun.com charl...' -- The document seems to lack a disclaimer for pre-RFC5378 work, but may have content which was first submitted before 10 November 2008. If you have contacted all the original authors and they are all willing to grant the BCP78 rights to the IETF Trust, then this is fine, and you can ignore this comment. If not, you may need to add the pre-RFC5378 disclaimer. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- Couldn't find a document date in the document -- date freshness check skipped. -- Found something which looks like a code comment -- if you have code sections in the document, please surround them with '' and '' lines. Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) -- Possible downref: Non-RFC (?) normative reference: ref. '1' -- Possible downref: Non-RFC (?) normative reference: ref. '2' == Outdated reference: A later version (-15) exists of draft-ietf-svrloc-protocol-v2-10 ** Obsolete normative reference: RFC 2373 (ref. '4') (Obsoleted by RFC 3513) ** Obsolete normative reference: RFC 1766 (ref. '5') (Obsoleted by RFC 3066, RFC 3282) -- Possible downref: Non-RFC (?) normative reference: ref. '6' ** Obsolete normative reference: RFC 2396 (ref. '7') (Obsoleted by RFC 3986) ** Obsolete normative reference: RFC 2234 (ref. '8') (Obsoleted by RFC 4234) ** Obsolete normative reference: RFC 2222 (ref. '9') (Obsoleted by RFC 4422, RFC 4752) -- Unexpected draft version: The latest known version of draft-ietf-svrloc-lpr-scheme is -00, but you're referring to -02. -- Possible downref: Normative reference to a draft: ref. '11' ** Obsolete normative reference: RFC 2279 (ref. '13') (Obsoleted by RFC 3629) -- Possible downref: Non-RFC (?) normative reference: ref. '14' -- Possible downref: Non-RFC (?) normative reference: ref. '15' -- Possible downref: Non-RFC (?) normative reference: ref. '16' Summary: 15 errors (**), 0 flaws (~~), 4 warnings (==), 11 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 1 Service Location Working Group Erik Guttman 2 INTERNET DRAFT Charles Perkins 3 James Kempf 4 27 October 1998 Sun Microsystems 6 Service Templates and service: Schemes 7 draft-ietf-svrloc-service-scheme-12.txt 9 Status of This Memo 11 This document is a submission by the Service Location Working Group 12 of the Internet Engineering Task Force (IETF). Comments should be 13 submitted to the srvloc@srvloc.org mailing list. 15 Distribution of this memo is unlimited. 17 This document is an Internet-Draft. Internet-Drafts are working 18 documents of the Internet Engineering Task Force (IETF), its areas, 19 and its working groups. Note that other groups may also distribute 20 working documents as Internet-Drafts. 22 Internet-Drafts are draft documents valid for a maximum of six months 23 and may be updated, replaced, or obsoleted by other documents at 24 any time. It is inappropriate to use Internet- Drafts as reference 25 material or to cite them other than as ``work in progress.'' 27 To view the entire list of current Internet-Drafts, please check 28 the ``1id-abstracts.txt'' listing contained in the Internet-Drafts 29 Shadow Directories on ftp.is.co.za (Africa), ftp.nordu.net (Northern 30 Europe), ftp.nis.garr.it (Southern Europe), munnari.oz.au (Pacific 31 Rim), ftp.ietf.org (US East Coast), or ftp.isi.edu (US West Coast). 33 Abstract 35 The "service:" URL scheme name is used to define URLs (called 36 "service: URLs" in this document) that are primarily intended to 37 be used by the Service Location Protocol in order to distribute 38 service access information. These schemes provide an extensible 39 framework for client-based network software to obtain configuration 40 information required to make use of network services. When 41 registering a service: URL, the URL is accompanied by a set of 42 well-defined attributes which define the service. These attributes 43 convey configuration information to client software, or service 44 characteristics meaningful to end users. 46 This document describes a formal procedure for defining and 47 standardizing new service types and attributes for use with the 48 "service:" scheme. The formal descriptions of service types and 49 attributes are templates that are human and machine understandable. 50 They SHOULD be used by administrative tools to parse service 51 registration information and by client applications to provide 52 localized translations of service attribute strings. 54 Contents 56 Status of This Memo i 58 Abstract i 60 1. Introduction 2 61 1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 3 62 1.2. Service Location Protocol . . . . . . . . . . . . . . . . 4 63 1.2.1. Compatibility with SLPv1 . . . . . . . . . . . . 4 65 2. Service URL Syntax and Semantics 5 66 2.1. Service URL Syntax . . . . . . . . . . . . . . . . . . . 5 67 2.2. Service URL Semantics . . . . . . . . . . . . . . . . . . 7 68 2.3. Use of service: URLs . . . . . . . . . . . . . . . . . . 8 69 2.4. Specifying the Service Type-Specific URL Syntax . . . . . 9 70 2.5. Accommodating Abstract Service Types . . . . . . . . . . 9 71 2.5.1. Advertising Abstract Service Types . . . . . . . 10 73 3. Syntax and Semantics of Service Type Specifications 11 74 3.1. Syntax of Service Type Templates . . . . . . . . . . . . 11 75 3.2. Semantics of Service Type Templates . . . . . . . . . . . 14 76 3.2.1. Definition of a Service Template . . . . . . . . 14 77 3.2.2. Service Type . . . . . . . . . . . . . . . . . . 15 78 3.2.3. Version Number . . . . . . . . . . . . . . . . . 15 79 3.2.4. Description . . . . . . . . . . . . . . . . . . . 15 80 3.2.5. Syntax of the Service Type-specific URL Part . . 15 81 3.2.6. Attribute Definition . . . . . . . . . . . . . . 16 83 4. A Process For Standardizing New Service Types 20 85 5. IANA Considerations 21 87 6. Internationalization Considerations 22 88 6.1. Language Identification and Translation . . . . . . . . . 23 90 7. Security Considerations 23 92 A. Service Template Examples 24 93 A.1. FOO . . . . . . . . . . . . . . . . . . . . . . . . . . . 24 94 A.2. Abstract Service Type: Net-Transducer . . . . . . . . . 26 95 A.3. Concrete Service Type: Net-Transducer:Thermometer . . . 27 96 A.4. service: URLs and SLP . . . . . . . . . . . . . . . . . . 28 98 B. Full Copyright Statement 30 99 C. Acknowledgments 30 101 1. Introduction 103 This document describes a URL scheme, called service: URL, which 104 defines network access information for network services using a 105 formal notation. In addition it describes how to define a set of 106 attributes to associate with a service: URL. These attributes will 107 allow end users and programs to select between network services of 108 the same type that have different capabilities. The attributes 109 are defined in a template document that is readable by people and 110 machines. 112 A client uses attributes to select a particular service. Service 113 selection occurs by obtaining the service: URL that offers the right 114 configuration for the client. Service type templates define the 115 syntax of service: URLs for a particular service type, as well as the 116 attributes which accompany a service: URL in a service registration. 118 Templates are used for the following distinct purposes: 120 1. Standardization 122 The template is reviewed before it is standardized. Once it is 123 standardized, all versions of the template are archived by IANA. 125 2. Service Registration 127 Servers making use of the Service Location Protocol [3] register 128 themselves and their attributes. They use the templates to 129 generate the service registrations. In registering, the service 130 must use the specified values for its attributes. 132 3. Client presentation of Service Information 134 Client applications may display service information. The 135 template provides type information and explanatory text which may 136 be helpful in producing user interfaces. 138 4. Internationalization 140 Entities with access to the template for a given service type in 141 two different languages may translate between the two languages. 143 A service may register itself in more than one language using 144 templates, though it has been configured by an operator who 145 registered service attributes in a single language. 147 All grammar encoding follows the Augmented BNF (ABNF) [8] for syntax 148 specifications. 150 1.1. Terminology 152 This section introduces some terminology for describing service: 153 URLs. 155 service scheme 157 A URL scheme whose name starts with the string "service:" and 158 is followed by the service type name, constructed according to 159 the rules in this document. An example is "service:lpr:" for 160 the lpr print service [11]. 162 service: URL 164 A URL constructed according to the service scheme definition. 165 It typically provides at least the following: The name of an 166 access protocol, and an address locating this service. The 167 service: URL may include url path information specific to the 168 type of service, as well as attribute information encoded 169 according to the URL grammar. The service: URL is used by 170 the Service Location Protocol to register and discover the 171 location of services. It may be used by other protocols and in 172 documents as well. 174 service type 176 A name identifying the semantics by which the remainder of 177 the service: URL is to be understood. It may denote either a 178 particular network protocol, or an abstract service associated 179 with a variety of protocols. If the service type denotes a 180 particular protocol, then the service type name SHOULD either 181 be assigned the name of a particular well known port [2] by 182 convention or be the Assigned Numbers name for the service [1]. 184 abstract service type 186 A service type name which is associated with a variety of 187 different protocols. An example is given in Section A. 188 Section 2 discusses various ways that abstract types can be 189 accommodated. 191 service registration 193 A service: URL and optionally a set of attributes comprise 194 a service registration. This registration is made by or on 195 behalf of a given service. The URL syntax and attributes must 196 conform to the service template for the registered service. 198 service template 200 A formal description of the service attributes and service 201 scheme associated with a particular service type. 203 1.2. Service Location Protocol 205 The Service Location Protocol version 2 [3] allows service: URLs to 206 be registered and discovered, though service: URLs may be also used 207 in other contexts. 209 Client applications discover service registrations by issuing queries 210 for services of a particular type, specifying the attributes of 211 the service: URLs to return. Clients retrieve the attributes of a 212 particular service by supplying its service: URL. Attributes for all 213 service registrations of a particular type can also be retrieved. 215 Services may register themselves, or registrations may be made on 216 their behalf. These registrations contain a service: URL, and 217 possibly attributes and digital signatures. 219 1.2.1. Compatibility with SLPv1 221 This document adopts the encoding conventions of SLPv2. 223 Compatibility with SLPv1 [12] is possible, if the following 224 conventions are observed: 226 1. Abstract service types must not be used. SLPv2 specifies the 227 use of Service URLs with abstract service types. SLPv1 does not 228 support them. Thus, a service template which is to serve both 229 SLPv1 and SLPv2 must not use abstract service types. 231 2. The syntax for representing opaque values in this document is 232 consistent with SLPv2. The syntax must be converted for use with 233 SLPv1. Instead of a sequence of "\FF" then "\" HEXDIG HEXDIG for 234 each byte in the opaque value, SLPv1 uses radix-64 notation. 236 3. Escape characters are significantly differently in SLPv1 and 237 SLPv2. Instead of using excaped byte notation for escaped 238 characters, SLPv1 uses the HTML convention `&' `#' 1*DIGIT `;'. 240 2. Service URL Syntax and Semantics 242 This section describes the syntax and semantics of service: URLs. 244 2.1. Service URL Syntax 246 The syntax of the service: URL MUST conform to an 'absolute URI' as 247 defined by [7]. The syntax of a service: URL differs enough from a 248 'generic URI' that it is best to treat it as an opaque URI unless a 249 specific parser for the service: URL is available. 251 All service: URLs have the same syntax up to the 'url-part' The 252 syntax for a service URL depends on the service type following the 253 service scheme. All service: URLs have a service access point 254 portion, indicating the address of the service to access. 256 The syntax for the field depends upon the service type 257 definition. The field is the service access point, and 258 describes how to access the service. In addition, although 259 both upper case and lower case characters are recognized in the 260 field for convenience, the name is case-folded into 261 lower case. Service types are therefore not distinguished on the 262 basis of case, so, for example, "http" and "HTTP" designate the same 263 service type. This is consistent with general URL practice, as 264 outlined in [7]. 266 The ABNF for a service: URL is: 268 service: URL = "service:" service-type ":" sap 269 service-type = abstract-type ":" url-scheme / concrete-type 270 abstract-type = type-name [ "." naming-auth ] 271 concrete-type = protocol [ "." naming-auth ] 272 type-name = resname 273 naming-auth = resname 274 url-scheme = resname 275 ; A recognized URL scheme name, standardized 276 ; either through common practice or through 277 ; approval of a standards body. 278 resname = ALPHA [ 1*(ALPHA / DIGIT / "+" / "-") ] 279 sap = site [url-part] 280 site = ipsite / atsite / ipxsite 281 ipsite = "//" [ [ user "@" ] hostport ] 282 hostport = host [ ":" port ] 283 host = hostname / hostnumber 284 hostname = *( domainlabel "." ) toplabel 285 alphanum = ALPHA / DIGIT 286 domainlabel = alphanum / alphanum *[alphanum / "-"] alphanum 287 toplabel = ALPHA / ALPHA *[ alphanum / "-" ] alphanum 288 hostnumber = ipv4-number / ipv6-number 289 ipv4-number = 1*3DIGIT 3("." 1*3DIGIT) 290 ipv6-number = v6num "-" 6( [v6num] "-") v6num ".ipv6" 291 ; Text represented IPv6 address syntax is as 292 ; RFC2373 [4] Section 2.2, with ':' replaced 293 ; by '-'. 294 v6num = 1*4HEXDIGIT 295 port = 1*DIGIT 296 ; A port number must be included if the 297 ; protocol field does not have an IANA 298 ; assigned port number. 299 user = *[ uchar / ";" / "+" / "&" / "=" ] 300 ipxsite = "/ipx/" ipx-net ":" ipx-node ":" ipx-socket 301 ipx-net = 8 HEXDIGIT 302 ipx-node = 12 HEXDIGIT 303 ipx-socket = 4 HEXDIGIT 304 atsite = "/at/" at-object ":" at-type "" at-zone 305 at-object = 1*31apple-char 306 at-type = 1*31apple-char 307 at-zone = 1*31apple-char 308 apple-char = ALPHA / DIGIT / safe / escaped 309 = ; AppleAscii [14] values that are not 310 = ; from the restricted range must be escaped. 311 = ; NOTE: The escaped values do NOT correspond 312 = ; to UTF8 values here: They are AppleAscii 313 = ; bytes. 314 url-part = [ url-path ] [ attr-list ] 315 url-path = 1 * ( "/" *xchar ) 316 ; Each service type must define its 317 ; own syntax consistent 318 ; with [7]. 319 attr-list = 1 * ( ";" attr-asgn ) 320 attr-asgn = attr-id / attr-id "=" attr-value 321 safe = "$" / "-" / "_" / "." / "~" 322 extra = "!" / "*" / "'" / "(" / ")" / "," / "+" 323 uchar = unreserved / escaped 324 xchar = unreserved / reserved / escaped 325 escaped = 1*(`\' HEXDIG HEXDIG) 326 reserved = ";" / "/" / "?" / ":" / "@" / "&" / "=" / "+" 327 unreserved = ALPHA / DIGIT / safe / extra 329 IPX addresses [15] are composed of a network, node and socket number. 330 The IPX network number is a four-byte number, in network order and 331 expressed in hexadecimal, that signifies an IPX subnet. The node 332 element represents a network interface card. It is a six-byte 333 number, expressed in hexadecimal, that is usually the same as the 334 node ID of the interface card. The socket element represents a 335 specific service access point, given an IPX network and node. IPX 336 sockets are analogous to TCP/IP ports, and are not to be confused 337 with Berkeley sockets. 339 AppleTalk addresses [16] are composed of an object, type and zone. 340 The object is a human readable string. The type is an identifier, 341 not intentended for human readability. The zone refers to the 342 AppleTalk Zone name, which is also human readable. The characters 343 composing these names are drawn from the AppleAscii character 344 set [14]. Thus, they do not equate to escaped ASCII or UTF8 345 characters. The characters "=" and "*" are reserved and may not be 346 included in the names even in binary form. 348 In cases besides the AppleTalk grammar, some characters must be 349 escaped before use. To escape any character, precede the two digits 350 indicating its ASCII value by '%'. 352 2.2. Service URL Semantics 354 The service scheme-specific information following the "service:" 355 URL scheme identifier provides information necessary to access the 356 service. As described in the previous subsection, the form of a 357 service: URL is as follows: 359 service: URL = "service:" service-type ":" site url-path 361 where has one of the following forms could refer to an 362 , or if the service URL locates to an 363 IP, IPX or AppleTalk service access point, respectively. 365 As discussed in Section 1, the can be either a 366 concrete protocol name, or an abstract type name. 368 The field is typically either a domain name (DNS) or an IP 369 network protocol address for the service, and possibly a port number. 370 Note that use of DNS hostnames is preferred for ease of renumbering. 371 The field can be null if other information in the service URL 372 or service attributes is sufficient to use the service. 374 The field allows more information to be provided (by way of 375 and ) that can uniquely locate the service 376 or resource if the is not sufficient for that purpose. For 377 IP addresses, the field begins with "//". Other address 378 families supported are IPX [15] and AppleTalk [16]. 380 An field appears at the end of the field, 381 but is never required to exist in any service location registration. 383 The field is composed of a list of semicolon (";") 384 separated attribute assignments of the form: 386 attr-id "=" attr-value 388 or for keyword attributes: 390 attr-id 392 Attributes are part of service: URLs when the attributes are required 393 to access a particular service. For instance, an ACAP [10] service 394 might require that the client authenticate with it through Kerberos. 395 Including an attribute in the service registration allows the ACAP 396 client to make use of the correct SASL [9] authentication mechanism. 397 The ACAP server's registration might look like: 399 service:acap://some.where.net;authentication=KERBEROSV4 401 Note that there can be other attributes of an ACAP server which 402 are not appropriate to include in the URL. For instance, the list 403 of users who have access to the server is useful for selecting an 404 ACAP server, but is not required for a client to use the registered 405 service. 407 Attributes associated with the service: URL are not typically 408 included in the service: URL. They are stored and retrieved using 409 other mechanisms. The service: URL is uniquely identified with a 410 particular service agent or resource, and is used when registering or 411 requesting the attribute information. The Service Location Protocol 412 specifies how such information is registered by network services and 413 obtained by client software. 415 2.3. Use of service: URLs 417 The service: URL is intended to allow arbitrary client/server and 418 peer to peer systems to make use of a standardized dynamic service 419 access point discovery mechanism. 421 It is intended that service: URLs be selected according to the 422 suitability of associated attributes. A client application can 423 obtain the URLs of several services of the same type and distinguish 424 the most preferable among them by means of their attributes. The 425 client uses the service: URL to communicate directly to a service. 427 Attributes are specified with a formal service template syntax 428 described in Section 3. If a service: URL registration includes 429 attributes, the registering agent SHOULD also keep track of the 430 attributes which characterize the service. 432 Registrations can be checked against the formal attribute 433 specification defined in the template by the client or agent 434 representing the client. Service registration are typically done 435 using the Service Location Protocol [3] (SLP). SLP provides a 436 mechanism for service: URLs to be obtained dynamically, according to 437 the service's attributes. 439 It is also possible to obtain service: URLs from documents and using 440 other protocols. In this case, the URL may not be accompanied by 441 the service attributes. The context in which the URL appears should 442 make it clear, if possible, when the service is appropriate to use. 443 For example, in a mail message, a service might be recommended for 444 use when the user is in a branch office. Or, an HTML document might 445 include a service: URL as a pointer to a service, describing in text 446 what the service does and who is authorized to use it. 448 2.4. Specifying the Service Type-Specific URL Syntax 450 When a service type is specified, the specification includes the 451 definition of the syntax for all URLs that are registered by services 452 of that particular type. For instance, the "lpr" service type may be 453 defined with service: URLs in the following form: 455 service:printer:lpr://
/ 457 The section of the URL after the address of the printer: 459 "/" 461 is specific to the lpr service type and corresponds to the 462 field of the general service: URL syntax. This part is 463 specified when the lpr service type is specified. 465 2.5. Accommodating Abstract Service Types 467 An abstract service type is a service type that can be implemented by 468 a variety of different service agents. 470 In order to register an service: URL for an abstract service type the 471 'abstract-type' grammar rule described in section 3.1 is used. This 472 will result in a URL which includes enough information to use the 473 service, namely, the protocol, address and path information. Unlike 474 'concrete' service: URLs, however, the service type is not enough 475 to determine the service access. Rather, an abstract service type 476 denotes a class of service types. The following subsection discusses 477 this point in more detail. 479 2.5.1. Advertising Abstract Service Types 481 Some services may make use of several protocols that are in common 482 use and are distinct services in their own right. In these cases an 483 abstract service type is appropriate. What is essential is that all 484 the required information for the service is clearly defined. 486 For example, suppose a network service is being developed for 487 dynamically loading device drivers. The client requires the 488 following three pieces of information before it can successfully load 489 and instantiate the driver: 491 1. The protocol used to load the driver code, for example, "ftp", 492 "http" or "tftp" 494 2. A pathname identifying where the driver code is located, for 495 example "/systemhost/drivers/diskdrivers.drv", 497 3. The name of the driver, for example, "scsi". 499 The temptation is to form the first two items into a URL and embed 500 that into a service: URL. As an example which should be avoided, 502 service:ftp:/x3.bean.org/drivers/diskdrivers.drv;driver=scsi 504 is a service: URL which seems to indicate where to obtain the driver. 506 Rather, an abstract service-type SHOULD be used. The service type is 507 not "ftp", as the example indicates. Rather, it is "device-drivers". 508 The service: URL that should be used, consistent with the rules in 509 section [6], is the following: 511 service:device-drivers:ftp://x3.bean.org/drivers/diskdrivers.drv; 512 driver=scsi;platform=sys3.2-rs3000 514 Other URLs for the same service using other protocols are also 515 supported, as in: 517 service:device-drivers:tftp://x2.bean.org/vol3/disk/drivers.drv; 518 driver=scsi;platform=sys3.2-rs3000 520 service:device-drivers:http://www.bean.org/drivers/drivpak.drv; 521 driver=scsi;platform=sys3.2-rs3000 523 Using SLP, a search for the service type "device-drivers" may return 524 all of the three URLs listed above. The client selects the most 525 appropriate access protocol for the desired resource. 527 The fundamental requirement is that the abstract service type MUST 528 be well specified. This requirement is imposed so that program code 529 or human users have enough information to access the service. In 530 every case, a well-specified abstract type will include either an 531 access protocol and a network address where the service is available, 532 or an embedded URL for a standardized URL scheme that describes 533 how to access the service. In the example above, there are three 534 further requirements: A URL path is included for access protocols 535 indicating the document to download, and two attributes are included 536 to characterize the driver. 538 3. Syntax and Semantics of Service Type Specifications 540 Service type specifications are documents in a formal syntax defining 541 properties important to service registration. These properties are: 543 1. General information on the service type specification itself, 545 2. The syntax of the service type-specific part of the service URL, 547 3. The definition of attributes associated with a service. 549 The service type specification document is the service type template. 551 The following subsections describe the syntax and semantics of 552 service type templates. 554 3.1. Syntax of Service Type Templates 556 Service template documents are encoded in a simple form. They may 557 be translated into any language or character set, but the template 558 used for standardization MUST be encoded in the 0x00-0x7F subrange of 559 UTF8 [13] (which corresponds to ASCII character encoding) and be in 560 English. 562 A template document begins with a block of text assigning values to 563 five document identification items. The five identification items 564 can appear in any order within the block, but conventionally the 565 "template-type" item, which assigns the service type name, occurs at 566 the very top of the document in order to provide context for the rest 567 of the the document. The attribute definition item occurs after the 568 document identification items. 570 All items end with a blank line. The reserved characters are ";", 571 "%", "=", ",", "#", LF, and CR. Reserved characters MUST be escaped. 572 The escape sequence is the same as described in [7]. 574 The service template is encoded in a UTF8 character set, but 575 submitted as a part of an internet-draft, which is encoded in 576 ASCII characters. All characters which are outside of the ASCII 577 range MUST be escaped using the `\' HEXDIG HEXDIG syntax. For 578 example, the letter e accent aigue would be represented as "\c3\a9". 579 Unfortunately, this will detract from the readability of the service 580 template in the service template submission. Hopefully some public 581 domain tools will emerge for translating escaped UTF8 characters into 582 humanly readable ones. 584 Values in value lists are separated by commas. A value list is 585 terminated by a newline not preceded by a comma. If the newline is 586 preceded by a comma, the value list is interpreted to continue onto 587 the next line. 589 Attribute identifiers, attribute type names, and flags are all 590 case insensitive. For ease of presentation, upper and lower case 591 characters can be used to represent these in the template document. 592 Newlines are significant in the grammar. They delimit one item from 593 another, as well as separating parts of items internally. 595 String values are considered to be a sequence of non-whitespace 596 tokens potentially with embedded whitespace, separated from each 597 other by whitespace. Commas delimit lists of strings. String values 598 are trimmed so as to reduce any sequence of white space interior to a 599 string to a single white space. Preceding or trailing white space is 600 removed. For example: 602 " some value , another example " 604 is trimmed to 606 "some value" and "another example". 608 Note that there can be no ambiguity in string tokenization because 609 values in value lists are separated by a comma. String tokens are 610 not delimited by double quotes (") as is usually the case with 611 programming languages. 613 Attribute tags and values are useful for directory look-up. In this 614 case, decoding of character escapes and trimming white space MUST 615 be performed before string matching. In addition, string matching 616 SHOULD be case insensitive. 618 Templates obey the following ABNF [8] grammar: 620 template = tem-attrs attr-defs 621 tem-attrs = schemetype schemevers schemetext schemeurl 622 schemetype = "template-type=" scheme term 623 schemevers = "template-version=" version-no term 624 schemetext = "template-description=" newline desc term 625 schemeurl = "template-url-syntax=" newline url-bnf term 626 url-bnf = *[ com-chars ] 627 ; An ABNF describing the production 628 ; in the service: URL grammar of Section 2.1. 629 scheme = service-type [ "." naming-auth ] 630 service-type = scheme-name 631 naming-auth = scheme-name 632 scheme-name = ALPHA [1*schemechar] [ "." 1*schemechar ] 633 schemechar = ALPHA / DIGIT / "-" / "+" / 634 version-no = 1*DIGIT "." 1*DIGIT 635 langtag = 1*8ALPHA ["-" 1*8ALPHA] 636 ; See [5] 637 desc = *[ com-chars ] 638 ; A block of free-form text for reading by 639 ; people describing the service in a short, 640 ; informative manner. 641 term = newline newline 642 attr-defs = *( attr-def / keydef ) 643 attr-def = id "=" attrtail 644 keydef = id "=" "keyword" newline [help-text] newline 645 attrtail = type flags newline [value-list] [help-text] 646 [value-list] newline 647 id = 1*attrchar 648 type = "string" / "integer" / "boolean" / "opaque" 649 flags = ["m"/"M"] ["l"/"L"] ["o"/"O"] ["x"/"X"] 650 value-list = value newline / value "," value-list / 651 value "," newline value-list 652 help-text = 1*( "#" help-line ) 653 ; A block of free-form text for reading by 654 ; people describing the attribute and 655 ; its values. 656 help-line = *[ com-chars ] newline 657 attrchar = schemechar / ":" / "_" / "$" / "~" / "@" / "." / 658 "|" / "<" / ">" / "*" / "&" 659 value = string / integer / boolean / opaque 660 string = safe-char *[safe-char / white-sp] safe-char 661 integer = [ "+" | "-" ] 1*DIGIT 662 boolean = "true" / "false" 663 opaque = "\FF" 1*( "\" HEXDIG HEXDIG) 664 ; Each byte of opaque value is hex encoded. 665 ; The format conforms to SLPv2 [3]. 666 ; Newlines are ignored in decoding opaque 667 ; values. 668 com-chars = safe-char / white-sp / "," / ";"/ "%" 669 safe-char = attrchar / escaped / " " / "!" / '"' / "'" / 670 "|" / "(" / ")" / "+" / "-" / "." / ":" / 671 "=" / "?" / "[" / "]" / "{" / "/" / "{" / 672 "$" 673 ; All UTF8 printable characters are 674 ; included except ",", "%", ";", and "#". 675 escaped = 1*(`\' HEXDIG HEXDIG) 676 white-sp = SPACE / HT 677 newline = CR / ( CR LF ) 679 3.2. Semantics of Service Type Templates 681 The service type template defines the service attributes and service: 682 URL syntax for a particular service type. The attribute definition 683 includes the attribute type, default values, allowed values and other 684 information. 686 3.2.1. Definition of a Service Template 688 There are four items included in the service template. The semantics 689 of each item is summarized below. 691 - template-type 693 The scheme name of the service scheme. The scheme name consists 694 of the service type name and an optional naming authority name, 695 separated from the service type name by a period. See 3.2.2 for 696 the conventions governing service type names. 698 - template-version 700 The version number of the service type specification. 702 - template-description 704 A description of the service suitable for inclusion in text read 705 by people. 707 - template-url-syntax 709 The syntax of the service type-specific URL part of the service: 710 URL. 712 - attribute definitions 714 A collection of zero or more definitions for attributes 715 associated with the service in service registrations. 717 Each of the following subsections deals with one of these items. 719 3.2.2. Service Type 721 The service scheme consists of the service type name and an optional 722 naming authority name separated from the service type name by 723 a period. The service scheme is a string that is appended to 724 the 'service:' URL scheme identifier, and is the value of the 725 "template-type" item in the template document. If the naming 726 authority name is absent it is assumed to be IANA. 728 3.2.3. Version Number 730 The version number of the service type template is the value of the 731 "template-version" item. A draft proposal starts at 0.0, and the 732 minor number increments once per revision. A standardized template 733 starts at 1.0. Additions of optional attributes add one to the minor 734 number, and additions of required attributes, changes of definition, 735 or removal of attributes add one to the major number. The intent 736 is that an old service template still accurately, if incompletely, 737 defines the attributes of a service registration if the template only 738 differs from the registration in its minor version. See Section 4 739 for more detail on how to use the template-version attribute. 741 3.2.4. Description 743 The description is a block of text readable by people in the language 744 of the template and is the value of the "template-description" item. 745 It should be sufficient to identify the service to human readers and 746 provide a short, informative description of what the service does. 748 If the service type corresponds to a particular protocol, the 749 protocol specification must be cited here. The protocol need not be 750 a standardized protocol. The template might refer to a proprietary 751 specification, and refer the reader of the template to a contact 752 person for further information. 754 3.2.5. Syntax of the Service Type-specific URL Part 756 The syntax of the service type-specific part of the service: 757 URL is provided in the template document as the value of the 758 "template-url-syntax" item. The field of the service: 759 URL is designed to provide additional information to locate a service 760 when the field is not sufficient. The field 761 distinguishes URLs of a particular service type from those of another 762 service type. For instance, in the case of the lpr service type, the 763 must include the queue name [11], but other service types 764 may not require this information. 766 The syntax for the field MUST accompany the definition 767 of a new service type, unless the URL scheme has already been 768 standardized and is not a service: URL. The syntax is included in the 769 template document as an ABNF [8] following the rules for URL syntax 770 described in [7]. There is no requirement for a service scheme to 771 support a . The field can be very simple, 772 or even omitted. If the URL scheme has already been standardized, 773 the "template-url-syntax" item SHOULD include a reference to the 774 appropriate standardization documents. Abstract service types may 775 defer this field to the template documents describing their concrete 776 instances. 778 3.2.6. Attribute Definition 780 The bulk of the template is typically devoted to defining service 781 type-specific attributes. An attribute definition precisely 782 specifies the attribute's type, other restrictions on the attribute 783 (whether it is multi-valued, optional, etc), some text readable by 784 people describing the attribute, and lists of default and allowed 785 values. The only required information is the attribute's type, the 786 rest are optional. Registration, deregistration and the use of 787 attributes in queries can be accomplished using the Service Location 788 Protocol [3] or other means, and discussion of this is beyond the 789 scope of the document. 791 Attributes are used to convey information about a given service for 792 purposes of differentiating different services of the same type. 793 They convey information to be used in the selection of a particular 794 service to establish communicate with, either through a program 795 offering a human interface or programmatically. Attributes can be 796 encoded in different character sets and in different languages. The 797 procedure for doing this is described in Section 6. 799 An attribute definition begins with the specification of the 800 attribute's identifier and ends with a single empty line. Attributes 801 definitions have five components (in order of appearance in a 802 definition): 804 1. An attribute identifier which acts as the name of the attribute, 806 2. Attribute descriptors (type and flags), 808 3. An optional list of values which are assigned to the attribute by 809 default, 811 4. An optional block of text readable by people providing a short, 812 informative description of the attribute, 814 5. An optional list of allowed values which restrict the value or 815 values the attribute can take on. 817 3.2.6.1. The Attribute Identifier 819 An attribute definition starts with the specification of the 820 attribute's identifier. The attribute's identifier functions as the 821 name of the attribute. Note that the characters used to compose an 822 attribute identifier are restricted to those characters considered 823 unrestricted for inclusion in a URL according to [7]. The reason 824 is that services can display prominent attributes in their service: 825 URL registrations. Each attribute identifier must be unique in the 826 template. Since identifiers are case folded, upper case and lower 827 case characters are the same. 829 3.2.6.2. The Attribute Type 831 Attributes can have one of five different types: string, integer, 832 boolean, opaque, or keyword. The attribute's type specification is 833 separated from the attribute's identifier by an equal sign ("=") and 834 follows the equal sign on the same line. The string, signed integer, 835 and boolean types have the standard programming language or database 836 semantics. Integers are restricted to those signed values that can 837 be represented in 32 bits. The character set used to represent 838 strings is not specified at the time the template is defined, but 839 rather is determined by the service registration. Booleans have the 840 standard syntax. Opaques are byte escaped values that can be used 841 to represent any other kind of data. Keywords are attributes that 842 have no characteristics other than their existence (and possibly the 843 descriptive text in their definition). 845 Keyword and boolean attributes impose restrictions on the following 846 parts of the attribute definition. Keyword attribute definitions 847 MUST have no flag information following the type definition, nor any 848 default or allowed values list. Boolean attributes are single value 849 only, i.e., multi-valued boolean attributes are not allowed. 851 3.2.6.3. Attribute Flags 853 Flags determine other characteristics of an attribute. With the 854 exception of keyword attributes, which may not have any flags, 855 flags follow the attribute type on the same line as the attribute 856 identifier, and are separated from each other by whitespace. Flags 857 may appear in any order after the attribute type. Other information 858 must not follow the flags, and only one flag identifier of a 859 particular flag type is allowed per attribute definition. 861 The semantics of the flags are as follows: 863 - o or O 865 Indicates that the attribute is optional. If this flag is 866 missing, the attribute is required in every service registration. 868 - m or M 870 Indicates that the attribute can take on multiple values. If 871 this flag is present, every value in a multi-valued attribute 872 has the same type as the type specified in the type part of the 873 attribute definition. Boolean attributes must not include this 874 flag. 876 - l or L 878 Indicates that attribute is literal, i.e. is not meant to be 879 translated into other languages. If this flag is present, the 880 attribute is not considered to be readable by people and should 881 not be translated when the template is translated. See Section 6 882 for more information about translation. 884 - x or X 886 Indicates that clients SHOULD include the indicated attribute 887 in requests for services. Neglecting to include this attribute 888 will not sufficiently differentiate the service. If services are 889 obtained without selecting this attribute they will quite likely 890 be useless to the client. 892 The values for multivalued attributes are an unordered set. 893 Deletions of individual values from a multivalued attribute are not 894 supported, and deletion of the attribute causes the entire set of 895 values to be removed. 897 3.2.6.4. Default Value or List 899 If the attribute definition includes a default value or, in the 900 case of multivalued attributes, a default values list, it begins 901 on the second line of the attribute definition and continues 902 over the following lines until a line ends without a comma. As a 903 consequence, newlines cannot be embedded in values unless escaped. 904 See Section 2.1. 906 Particular attribute types and definitions restrict the default 907 values list. Keyword attributes must not have a list of defaults. 908 If an optional attribute's definition has an allowed values list, 909 then a default value or list is not optional but required. The 910 motivation for this is that defining an attribute with an allowed 911 values list is meant to restrict the values the attribute can take 912 on, and requiring a default value or list assures that the default 913 value is a member of the given set of allowed values. 915 The default value or list indicates what values the attribute is 916 given if no values are assigned to the attribute when a service 917 is registered. If an optional attribute's definition includes no 918 default value or list, the following defaults are assigned: 920 1. String values are assigned the empty string, 922 2. Integer values are assigned zero, 924 3. Boolean values are assigned false, 926 4. Opaque values are assigned a byte array containing no values, 928 5. Multi-valued attributes are initialized with a single value. 930 For purposes of translating nonliteral attributes, the default values 931 list is taken to be an ordered set, and translations MUST maintain 932 that order. 934 3.2.6.5. Descriptive Text 936 Immediately after the default values list, if any, a block of 937 descriptive text SHOULD be included in the attribute definition. 938 This text is meant to be readable by people, and should include 939 a short, informative description of the attribute. It may also 940 provide additional information, such as a description of the allowed 941 values. This text is primarily designed for display by interactive 942 browsing tools. The descriptive text is set off from the surrounding 943 definition by a crosshatch character ("#") at the beginning of 944 the line. The text should not, however, be treated as a comment 945 by parsing and other tools, since it is an integral part of the 946 attribute definition. Within the block of descriptive text, the text 947 is transferred verbatim, including indentation and line breaks, so 948 any formatting is preserved. 950 3.2.6.6. Allowed Values List 952 Finally, the attribute definition concludes with an optional 953 allowed values list. The allowed values list, if any, follows the 954 descriptive text, or, if the descriptive text is absent, the initial 955 values list. The syntax of the allowed values list is identical to 956 that of the initial values list. The allowed values list is also 957 terminated by a line that does not end in a comma. If the allowed 958 values list is present, assignment to attributes is restricted to 959 members of the list. 961 As with the default values list, the allowed values list is also 962 considered to be an ordered set for purposes of translation. 964 3.2.6.7. Conclusion of An Attribute Definition 966 An attribute definition concludes with a single empty line. 968 4. A Process For Standardizing New Service Types 970 New service types can be suggested simply by providing a service type 971 template and a short description about how to use the service. The 972 template MUST have its "template-version" template attribute set to 973 0.0. 975 MAJOR revision numbers come before the '.', MINOR revision numbers 976 come after the '.'. 978 The minor version number increments once with each change until it 979 achieves 1.0. There is no guarantee any version of the service 980 template is backward compatible before it reaches 1.0. 982 Once a service template has reached 1.0, the definition is "frozen" 983 for that version. New templates must be defined, of course, to 984 refine that definition, but the following rules must be followed: 986 A MINOR revision number signifies the introduction of a compatible 987 change. A MAJOR revision number signifies the introduction of an 988 incompatible change. This is formalized by the following rules: 990 - Any new optional attribute defined for the template increases 991 the minor version number by one. All other attributes for the 992 version must continue to be supported as before. A client which 993 supports 1.x can still use later versions of 1.y (where x "." "." 1063 Each of these fields are defined in Section 2. They 1064 correspond to the values of the template fields "type", 1065 "template-version". The files for the example templates in 1066 this document are called "foo.0.0.en", "Net-Transducer.0.0.en", 1067 "Net-Transducer:Thermometer.0.0.de" and 1068 "Net-Transducer:Thermomoter.0.0.en". See Section A. 1070 The reviewer will ensure that the template submission to IANA has the 1071 correct form and required fields. 1073 No service type template will be accepted for inclusion in the 1074 service template registry unless the submission includes a security 1075 considerations section and contact information for the template 1076 document author. 1078 The IANA will maintain a registry containing both the service type 1079 templates, and the template description document containing the 1080 service type template, including all previous versions. The IANA 1081 will receive notice to include a service template in the registry 1082 by email from the reviewer. This message will include the service 1083 template itself, which is to be registered. 1085 Neither the reviewer nor the IANA will take any position on claims of 1086 copyright or trademark issues with regard to templates. 1088 6. Internationalization Considerations 1090 The service: URL must be encoded using the rules set forth in [7]. 1091 The character set encoding is limited to specific ranges within the 1092 US-ASCII character set [6]. 1094 The template is encoded in UTF8 characters. 1096 6.1. Language Identification and Translation 1098 The language used in attribute strings should be identified 1099 supplying a Language Tag [5] in the Service Template submission (see 1100 Section 5). 1102 A program can translate a service registration from one language to 1103 another provided it has both the template of the language for the 1104 registration and the template of the desired target language. All 1105 standardized attributes are in the same order in both templates. 1106 All non-arbitrary strings, including the descriptive help text, is 1107 directly translatable from one language to another. Non-literal 1108 attribute definitions, attribute identifiers, attribute type names, 1109 attribute flags, and the boolean constants "true" and "false" are 1110 never translated. Translation of attribute identifiers is prohibited 1111 because, as with domain names, they can potentially be part of a 1112 service: URL and therefore their character set is restricted. In 1113 addition, as with variable identifiers in programming languages, they 1114 could become embedded into program code. 1116 All strings used in attribute values are assumed translatable unless 1117 explicitly defined as being literal, so that best effort translation 1118 (see below) does not modify strings which are meant to be interpreted 1119 by a program, not a person. 1121 An example of a translated service template is included in Section A. 1123 There are two ways to go about translation: standardization and best 1124 effort. 1126 When the service type is standardized, more than one document can 1127 be submitted for review. One service type description is approved 1128 as a master, so that when a service type template is updated in one 1129 language, all the translations (at least eventually) reflect the same 1130 semantics. 1132 If no document exists describing the standard translation of the 1133 service type, a 'best effort' translation for strings should be done. 1135 7. Security Considerations 1137 Service type templates provide information that is used to interpret 1138 information obtained by the Service Location Protocol. If these 1139 templates are modified or false templates are distributed, services 1140 may not correctly register themselves, or clients might not be able 1141 to interpret service information. 1143 The service: URLs themselves specify the service access point and 1144 protocol for a particular service type. These service: URLs could 1145 be distributed and indicate the location of a service other than 1146 that normally want to used. The Service Location Protocol [3] 1147 distributes service: URLs and has an authentication mechanism that 1148 allows service: URLs of registered services to be signed and for the 1149 signatures to be verified by clients. 1151 Each Service Template will include a security considerations section 1152 which will describe security issues with using the service scheme for 1153 the specific Service Type. 1155 A. Service Template Examples 1157 The text in the template example sections is to be taken as being a 1158 single file. They are completely fictitious (ie. the examples do 1159 not represent real services). 1161 The FOO example shows how to use service templates for an application 1162 that has very few attributes. Clients request the FOO server where 1163 their user data is located by including their user name as the value 1164 of the user attribute. 1166 The Net-Transducer example shows how abstract service types are 1167 defined and how a corresponding concrete instance is defined. A 1168 system might support any of several NetTransducer services. Here we 1169 give only one concrete instance of the abstract type. 1171 It is not necessary to register concrete templates for an abstract 1172 service type if the abstract service type template is completely 1173 clear as to what possible values can be used as a concrete type, and 1174 what their interpretation is. 1176 A.1. FOO 1178 The FOO service template submission example follows: 1180 Name of submitter: "Erik Guttman" 1181 Language of service template: en 1182 Security Considerations: 1183 If the USER and GROUPS attributes are included a 1184 possibility exists that the list of identities for users or groups 1185 can be discovered. This information would otherwise be difficult 1186 to discover. 1187 Template Text: 1188 -------------------------template begins here----------------------- 1189 template-type=FOO 1191 template-version=0.0 1193 template-description= 1194 The FOO service URL provides the location of an FOO service. 1196 template-url-syntax= 1197 url-path= ; There is no URL path defined for a FOO URL. 1199 users= string M L O 1200 # The list of all users which the FOO server supports. 1202 groups= string M L O 1203 # The list of all groups which the FOO server supports. 1204 --------------------------template ends here------------------------ 1206 This template could be internationalized by registering another 1207 version, say in German: 1209 Name of submitter: "Erik Guttman" 1210 Language of service template: de 1211 Security Considerations: 1212 Wenn die USER und GROUPS Eigenschaften inbegriffen sind,, 1213 besteht die Moeglichkeit, dass die Liste der Identitaeten 1214 von Benutzern oder Gruppen endeckt verden kann. Diese 1215 Information wurde unter anderen Umstaenden schwierig zu 1216 entdecken sein. 1218 Template Text: 1219 -------------------------template begins here----------------------- 1220 template-type=FOO 1222 template-version=0.0 1224 template-description= 1225 Der FOO Service URL zeigt die Stelle von einem Foo Service an. 1227 template-url-syntax= 1228 url-path= ; Es gibt keinen fuer den FOO URL definierten Pfad. 1230 users= string M L O 1231 # Die Liste aller Users, die der FOO Server unterstuetzt. 1233 groups= string M L O 1234 # Die Liste aller Gruppen, die der FOO Server unterstuetzt. 1235 --------------------------template ends here------------------------ 1237 Note that the attribute tags are not translated. If translations 1238 are desired, the suggested convention for doing so is to define a 1239 separate attribute called localize- for each attribute tag which 1240 is to be localized. This will aid in displaying the attribute tags 1241 in a human interface. 1243 For example, in this case above, the following two attributes could 1244 be defined: 1246 localize-users= string 1247 Benutzer 1249 localize-groups= string 1250 Gruppen 1252 The attributes (in SLPv2 attribute list format) for a service 1253 registration of a FOO service based on this template, in German, 1254 could be: 1256 (users=Hans,Fritz),(groups=Verwaltung,Finanzbuchhaltung), 1257 (template-type=FOO),(template-version=0.0),(template-description= 1258 Der FOO Service URL zeigt die Stelle von einem Foo Service an.), 1259 (template-url-syntax= \OD url-path= ; Es gibt kein fuer den FOO 1260 URL definiert Pfad. \OD),(localize-users=Benutzer), 1261 (localize-groups=Gruppen) 1263 Anyone obtaining these attributes could display "Benutzer=Hans,Fritz" 1264 in a human interface using the included information. 1266 A.2. Abstract Service Type: Net-Transducer 1268 An example submission of an abstract service type template is: 1270 Name of submitter: "Erik Guttman" 1271 Language of service template: en 1272 Security Considerations: 1273 See the security considerations of the concrete service types. 1274 Template Text: 1275 -------------------------template begins here----------------------- 1276 template-type=Net-Transducer 1278 template-version=0.0 1280 template-description= 1281 This is an abstract service type. The purpose of the Net- 1282 Transducer service type is to organize into a single category 1283 all network enabled Transducers which have certain properties. 1285 template-url-syntax= 1286 url-path= ; Depends on the concrete service type. 1287 ; See these templates. 1289 sample-units= string L 1290 # The units of sample that the Transducer provides, for instance 1291 # C (degrees Celsius), V (Volts), kg (Kilograms), etc. 1293 sample-resolution= string L 1294 # The resolution of the Transducer. For instance, 10^-3 means 1295 # that the Transducer has resolution to 0.001 unit. 1297 sample-rate= integer L 1298 # The speed at which samples are obtained per second. For 1299 # instance 1000 means that one sample is obtained every millisecond. 1301 --------------------------template ends here------------------------ 1303 A.3. Concrete Service Type: Net-Transducer:Thermometer 1305 This is another service template submission example, supplying a 1306 concrete service type corresponding to the abstract template above. 1308 Name of submitter: "Erik Guttman" 1309 Language of service template: en 1310 Security Considerations: 1311 There is no authentication of the Transducer output. Thus, 1312 the Thermometer output could easily be spoofed. 1313 Template Text: 1314 -------------------------template begins here----------------------- 1315 template-type=service:Net-Transducer:Thermometer 1317 template-version=0.0 1319 template-description= 1320 The Thermometer is a Net-Transducer capable of reading temperature. 1321 The data is read by opening a TCP connection to one of the ports 1322 in the service URL and reading an ASCII string until an NULL 1323 character is encountered. The client may continue reading data at 1324 no faster than the sample-rate, or close the connection. 1326 template-url-syntax= 1327 url-path = "ports=" ports-list 1328 port-list = port / port "," ports 1329 port = 1*DIGIT 1330 ; See the Service URL production rule. 1331 ; These are the ports connections can be made on. 1333 location-description=string 1334 # The location where the Thermometer is located. 1336 operator=string O 1337 # The operator to contact to have the Thermometer serviced. 1339 --------------------------template ends here------------------------ 1341 A.4. service: URLs and SLP 1343 A user with an FOO enabled calendar application should not be 1344 bothered with knowing the address of their FOO server. The 1345 calendar client program can use SLP to obtain the FOO service: URL 1346 automatically, say 'service:foo://server1.nosuch.org', by issuing 1347 a Service Request. In the event that this FOO server failed, the 1348 Calendar client can issue the same service request again to find the 1349 backup FOO server, say 'service:foo://server2.nosuch.org'. In both 1350 cases, the service: URL conforms to the FOO service template as do 1351 the associated attributes (user and group.) 1353 A network thermometer based on the above template could be advertised 1354 with the SLPv2 attribute list: 1356 URL = service:net-transducer:thermometer://v33.test/ports=3211 1357 Attributes = (location-description=Missile bay 32), 1358 (operator=Joe Agent), (sample-units=C), 1359 (sample-resolution=10^-1),(sample-rate=10), 1360 (template-type=service:net-transducer:thermometer), 1361 (template-version=0.0),(template-description= 1362 The Thermometer is a Net-Transducer capable of reading temperature. 1363 The data is read by opening a TCP connection to one of the ports 1364 in the service URL and reading an ASCII string until an NULL 1365 character is encountered. The client may continue reading data at 1366 no faster than the sample-rate, or close the connection.), 1367 (template-url-syntax= \0D "ports=" port-list \OD 1368 port-list = port / port "," ports \OD 1369 port = 1*DIGIT \OD 1370 ; See the Service URL production rule. \OD 1371 ; These are the ports connections can be made on.\OD) 1373 This might be very useful for a technician who wanted to find a 1374 Thermometers in Missile bay 32, for example. 1376 Note that the template attributes are advertised. The 1377 template-url-syntax value requires explicit escaped CR characters so 1378 that the ABNF syntax is correct. 1380 B. Full Copyright Statement 1382 Copyright (C) The Internet Society (1997). All Rights Reserved. 1384 This document and translations of it may be copied and furnished to 1385 others, and derivative works that comment on or otherwise explain it 1386 or assist in its implmentation may be prepared, copied, published 1387 and distributed, in whole or in part, without restriction of any 1388 kind, provided that the above copyright notice and this paragraph 1389 are included on all such copies and derivative works. However, 1390 this document itself may not be modified in any way, such as by 1391 removing the copyright notice or references to the Internet Society 1392 or other Internet organizations, except as needed for the purpose 1393 of developing Internet standards in which case the procedures 1394 for copyrights defined in the Internet Standards process must be 1395 followed, or as required to translate it into languages other than 1396 English. 1398 The limited permissions granted above are perpetual and will not be 1399 revoked by the Internet Society or its successors or assigns. 1401 This document and the information contained herein is provided on an 1402 "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING 1403 TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING 1404 BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION 1405 HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF 1406 MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE." 1408 C. Acknowledgments 1410 Thanks to Michael Day and Leland Wallace for assisting with the IPX 1411 and AppleTalk address syntax portions. Ryan Moats provided valuable 1412 feedback throughout the writing of this document. 1414 References 1416 [1] Protocol and service names, October 1994. 1417 ftp://ftp.isi.edu/in-notes/iana/assignments/service-names. 1419 [2] Port numbers, July 1997. 1420 ftp://ftp.isi.edu/in-notes/iana/assignments/port-numbers. 1422 [3] E. Guttman, C. Perkins, J. Kempf Service Location Protocol, 1423 Version 2. draft-ietf-svrloc-protocol-v2-10.txt, October, 1998. 1424 (work in progress). 1426 [4] R. Hinden, S. Deering IP Version 6 Addressing Architecture RFC 1427 2373, July 1998. 1429 [5] H. Alvestrand. Tags for the Identification of Languages. RFC 1430 1766, March 1995. 1432 [6] ANSI. Coded Character Set -- 7-bit American Standard code for 1433 Information Interchange. X3.4-1986, 1986. 1435 [7] T. Berners-Lee, R. Fielding, and L. Masinter. Uniform Resource 1436 Identifiers (URI): Generic Syntax. RFC 2396, August 1998. 1438 [8] D. Crocker and P. Overell. Augmented BNF for Syntax 1439 Specifications: ABNF. RFC 2234, November 1997. 1441 [9] J. Myers. Simple Authentication and Security Layer (SASL). RFC 1442 2222, October 1997. 1444 [10] C. Newman and J. G. Myers. ACAP -- Application Configuration 1445 Access Prototol. RFC 2244, November 1997. 1447 [11] Pete St. Pierre. Definition of lpr: URLs for use with Service 1448 Location. draft-ietf-svrloc-lpr-scheme-02.txt, November 1997. 1449 (work in progress). 1451 [12] J. Veizades, E. Guttman, C. Perkins, and S. Kaplan. Service 1452 Location Protocol. RFC 2165, July 1997. 1454 [13] F. Yergeau. UTF-8, a transformation format of ISO 10646. RFC 1455 2279, January 1998. 1457 [14] Apple Computer. Inside Macintosh: Text. Addison Wesley, 1993 1459 [15] Novell, Inc. IPX RIP and SAP Router Specification. Part Number 1460 107-000029-001, Version 1.30. May 23, 1996. 1462 [16] S. Gursharan, R. Andrews, and A. Oppenheimer. Inside AppleTalk. 1463 Addison-Wesley, 1990. 1465 Authors' Addresses 1467 Questions about this memo can be directed to: 1469 Erik Guttman Charles E. Perkins James Kempf 1470 Sun Microsystems Sun Microsystems Sun Microsystems 1471 Bahnstr. 2 901 San Antonio Rd. 901 San Antonio Rd. 1472 74915 Waibstadt Palo Alto, CA, 94303 Palo Alto, CA, 94303 1473 Germany USA USA 1474 +49 7263 911484 +1 650 786 6464 +1 650 786 5890 1475 +1 650 786 5992 +1 650 786 6445 (fax) +1 650 786 6445 (fax) 1476 erik.guttman@sun.com charles.perkins@sun.com james.kempf@sun.com