idnits 2.17.1 draft-ietf-svrloc-service-scheme-14.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? == 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 5 instances of too long lines in the document, the longest one being 3 characters in excess of 72. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the RFC 3978 Section 5.4 Copyright Line does not match the current year == Line 1501 has weird spacing: '...sun.com cperk...' == Using lowercase 'not' together with uppercase 'MUST', 'SHALL', 'SHOULD', or 'RECOMMENDED' is not an accepted usage according to RFC 2119. Please use uppercase 'NOT' together with RFC 2119 keywords (if that is what you mean). Found 'MUST not' in this paragraph: Concrete service templates inherit all attributes defined in the abstract service template from which the concrete service template was derived. Attribute defined in the abstract service template MUST not be defined in the concrete service template as well. This simplifies interpretation of templates. -- 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) == Unused Reference: '15' is defined on line 1484, but no explicit reference was found in the text -- Possible downref: Non-RFC (?) normative reference: ref. '1' -- Possible downref: Non-RFC (?) normative reference: ref. '2' ** Obsolete normative reference: RFC 1766 (ref. '3') (Obsoleted by RFC 3066, RFC 3282) -- Possible downref: Non-RFC (?) normative reference: ref. '4' ** Obsolete normative reference: RFC 2396 (ref. '5') (Obsoleted by RFC 3986) -- Possible downref: Non-RFC (?) normative reference: ref. '7' ** Obsolete normative reference: RFC 2234 (ref. '8') (Obsoleted by RFC 4234) -- Possible downref: Non-RFC (?) normative reference: ref. '9' == Outdated reference: A later version (-15) exists of draft-ietf-svrloc-protocol-v2-04 ** Obsolete normative reference: RFC 2222 (ref. '11') (Obsoleted by RFC 4422, RFC 4752) ** Obsolete normative reference: RFC 2434 (ref. '12') (Obsoleted by RFC 5226) -- Possible downref: Non-RFC (?) normative reference: ref. '14' ** Obsolete normative reference: RFC 2279 (ref. '16') (Obsoleted by RFC 3629) Summary: 12 errors (**), 0 flaws (~~), 6 warnings (==), 9 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 5 February 1999 Sun Microsystems 6 Service Templates and service: Schemes 7 draft-ietf-svrloc-service-scheme-14.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 and is in full conformance with 18 all provisions of Section 10 of RFC2026. Internet-Drafts are working 19 documents of the Internet Engineering Task Force (IETF), its areas, 20 and its working groups. Note that other groups may also distribute 21 working documents as Internet-Drafts. 23 Internet-Drafts are draft documents valid for a maximum of six months 24 and may be updated, replaced, or obsoleted by other documents at 25 any time. It is inappropriate to use Internet- Drafts as reference 26 material or to cite them other than as "work in progress." 28 The list of current Internet-Drafts can be accessed at 29 http://www.ietf.org/ietf/1id-abstracts.txt 31 The list of Internet-Draft Shadow Directories can be accessed at 32 http://www.ietf.org/shadow.html. 34 Abstract 36 The "service:" URL scheme name is used to define URLs (called 37 "service: URLs" in this document) that are primarily intended to 38 be used by the Service Location Protocol in order to distribute 39 service access information. These schemes provide an extensible 40 framework for client-based network software to obtain configuration 41 information required to make use of network services. When 42 registering a service: URL, the URL is accompanied by a set of 43 well-defined attributes which define the service. These attributes 44 convey configuration information to client software, or service 45 characteristics meaningful to end users. 47 This document describes a formal procedure for defining and 48 standardizing new service types and attributes for use with the 49 "service:" scheme. The formal descriptions of service types and 50 attributes are templates that are human and machine understandable. 51 They SHOULD be used by administrative tools to parse service 52 registration information and by client applications to provide 53 localized translations of service attribute strings. 55 Contents 57 Status of This Memo i 59 Abstract i 61 1. Introduction 2 62 1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 3 63 1.2. Service Location Protocol . . . . . . . . . . . . . . . . 4 64 1.2.1. Compatibility with SLPv1 . . . . . . . . . . . . 4 66 2. Service URL Syntax and Semantics 5 67 2.1. Service URL Syntax . . . . . . . . . . . . . . . . . . . 5 68 2.2. Service URL Semantics . . . . . . . . . . . . . . . . . . 7 69 2.3. Use of service: URLs . . . . . . . . . . . . . . . . . . 8 70 2.4. Specifying the Service Type-Specific URL Syntax . . . . . 9 71 2.5. Accommodating Abstract Service Types . . . . . . . . . . 9 72 2.5.1. Advertising Abstract Service Types . . . . . . . 10 74 3. Syntax and Semantics of Service Type Specifications 11 75 3.1. Syntax of Service Type Templates . . . . . . . . . . . . 11 76 3.2. Semantics of Service Type Templates . . . . . . . . . . . 14 77 3.2.1. Definition of a Service Template . . . . . . . . 14 78 3.2.2. Service Type . . . . . . . . . . . . . . . . . . 15 79 3.2.3. Version Number . . . . . . . . . . . . . . . . . 15 80 3.2.4. Description . . . . . . . . . . . . . . . . . . . 16 81 3.2.5. Syntax of the Service Type-specific URL Part . . 16 82 3.2.6. Attribute Definition . . . . . . . . . . . . . . 16 84 4. A Process For Standardizing New Service Types 20 86 5. IANA Considerations 22 88 6. Internationalization Considerations 23 89 6.1. Language Identification and Translation . . . . . . . . . 23 91 7. Security Considerations 24 93 A. Service Template Examples 24 94 A.1. FOO . . . . . . . . . . . . . . . . . . . . . . . . . . . 25 95 A.2. Abstract Service Type: Net-Transducer . . . . . . . . . 27 96 A.3. Concrete Service Type: Net-Transducer:Thermometer . . . 28 97 A.4. service: URLs and SLP . . . . . . . . . . . . . . . . . . 28 99 B. Full Copyright Statement 30 100 C. Acknowledgments 30 102 1. Introduction 104 This document describes a URL scheme, called service: URL, which 105 defines network access information for network services using a 106 formal notation. In addition it describes how to define a set of 107 attributes to associate with a service: URL. These attributes will 108 allow end users and programs to select between network services of 109 the same type that have different capabilities. The attributes 110 are defined in a template document that is readable by people and 111 machines. 113 A client uses attributes to select a particular service. Service 114 selection occurs by obtaining the service: URL that offers the right 115 configuration for the client. Service type templates define the 116 syntax of service: URLs for a particular service type, as well as the 117 attributes which accompany a service: URL in a service registration. 119 Templates are used for the following distinct purposes: 121 1. Standardization 123 The template is reviewed before it is standardized. Once it is 124 standardized, all versions of the template are archived by IANA. 126 2. Service Registration 128 Servers making use of the Service Location Protocol [10] register 129 themselves and their attributes. They use the templates to 130 generate the service registrations. In registering, the service 131 must use the specified values for its attributes. 133 3. Client presentation of Service Information 135 Client applications may display service information. The 136 template provides type information and explanatory text which may 137 be helpful in producing user interfaces. 139 4. Internationalization 141 Entities with access to the template for a given service type in 142 two different languages may translate between the two languages. 144 A service may register itself in more than one language using 145 templates, though it has been configured by an operator who 146 registered service attributes in a single language. 148 All grammar encoding follows the Augmented BNF (ABNF) [8] for syntax 149 specifications. 151 1.1. Terminology 153 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 154 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 155 document are to be interpreted as described in RFC 2119 [6]. 157 The following terminology is used for describing service: URLs. 159 service scheme 161 A URL scheme whose name starts with the string "service:" and 162 is followed by the service type name, constructed according to 163 the rules in this document. 165 service: URL 167 A URL constructed according to the service scheme definition. 168 It typically provides at least the following: The name of an 169 access protocol, and an address locating this service. The 170 service: URL may include url path information specific to the 171 type of service, as well as attribute information encoded 172 according to the URL grammar. The service: URL is used by 173 the Service Location Protocol to register and discover the 174 location of services. It may be used by other protocols and in 175 documents as well. 177 service type 179 A name identifying the semantics by which the remainder of 180 the service: URL is to be understood. It may denote either a 181 particular network protocol, or an abstract service associated 182 with a variety of protocols. If the service type denotes a 183 particular protocol, then the service type name SHOULD either 184 be assigned the name of a particular well known port [2] by 185 convention or be the Assigned Numbers name for the service [1]. 187 abstract service type 189 A service type name which is associated with a variety of 190 different protocols. An example is given in Section A. 191 Section 2 discusses various ways that abstract types can be 192 accommodated. 194 service registration 196 A service: URL and optionally a set of attributes comprise 197 a service registration. This registration is made by or on 198 behalf of a given service. The URL syntax and attributes must 199 conform to the service template for the registered service. 201 service template 203 A formal description of the service attributes and service 204 scheme associated with a particular service type. 206 1.2. Service Location Protocol 208 The Service Location Protocol version 2 [10] allows service: URLs to 209 be registered and discovered, though service: URLs may be also used 210 in other contexts. 212 Client applications discover service registrations by issuing queries 213 for services of a particular type, specifying the attributes of 214 the service: URLs to return. Clients retrieve the attributes of a 215 particular service by supplying its service: URL. Attributes for all 216 service registrations of a particular type can also be retrieved. 218 Services may register themselves, or registrations may be made on 219 their behalf. These registrations contain a service: URL, and 220 possibly attributes and digital signatures. 222 1.2.1. Compatibility with SLPv1 224 This document adopts the encoding conventions of SLPv2. 226 Compatibility with SLPv1 [[15]] is possible, if the following 227 conventions are observed: 229 1. Abstract service types must not be used. SLPv2 specifies the 230 use of Service URLs with abstract service types. SLPv1 does not 231 support them. Thus, a service template which is to serve both 232 SLPv1 and SLPv2 must not use abstract service types. 234 2. The syntax for representing opaque values in this document is 235 consistent with SLPv2. The syntax must be converted for use with 236 SLPv1. Instead of a sequence of "\FF" then "\" HEXDIG HEXDIG for 237 each byte in the opaque value, SLPv1 uses radix-64 notation. 239 3. Escape characters are significantly differently in SLPv1 and 240 SLPv2. Instead of using escaped byte notation for escaped 241 characters, SLPv1 uses the HTML convention `&' `#' 1*DIGIT `;'. 243 2. Service URL Syntax and Semantics 245 This section describes the syntax and semantics of service: URLs. 247 2.1. Service URL Syntax 249 The syntax of the service: URL MUST conform to an 'absolute URI' as 250 defined by [5]. The syntax of a service: URL differs enough from a 251 'generic URI' that it is best to treat it as an opaque URI unless a 252 specific parser for the service: URL is available. 254 All service: URLs have the same syntax up to the 'url-part' The 255 syntax for a service URL depends on the service type following the 256 service scheme. All service: URLs have a service access point 257 portion, indicating the address of the service to access. 259 The syntax for the field depends upon the service type 260 definition. The field is the service access point, and 261 describes how to access the service. In addition, although 262 both upper case and lower case characters are recognized in the 263 field for convenience, the name is case-folded into 264 lower case. Service types are therefore not distinguished on the 265 basis of case, so, for example, "http" and "HTTP" designate the same 266 service type. This is consistent with general URL practice, as 267 outlined in [5]. 269 The ABNF for a service: URL is: 271 service: URL = "service:" service-type ":" sap 272 service-type = abstract-type ":" url-scheme / concrete-type 273 abstract-type = type-name [ "." naming-auth ] 274 concrete-type = protocol [ "." naming-auth ] 275 type-name = resname 276 naming-auth = resname 277 url-scheme = resname 278 ; A recognized URL scheme name, standardized 279 ; either through common practice or through 280 ; approval of a standards body. 281 resname = ALPHA [ 1*(ALPHA / DIGIT / "+" / "-") ] 282 sap = site [url-part] 283 site = ipsite / atsite / ipxsite 284 ipsite = "//" [ [ user "@" ] hostport ] 285 hostport = host [ ":" port ] 286 host = hostname / hostnumber 287 hostname = *( domainlabel "." ) toplabel 288 alphanum = ALPHA / DIGIT 289 domainlabel = alphanum / alphanum *[alphanum / "-"] alphanum 290 toplabel = ALPHA / ALPHA *[ alphanum / "-" ] alphanum 291 hostnumber = ipv4-number 292 ipv4-number = 1*3DIGIT 3("." 1*3DIGIT) 293 port = 1*DIGIT 294 ; A port number must be included if the 295 ; protocol field does not have an IANA 296 ; assigned port number. 297 user = *[ uchar / ";" / "+" / "&" / "=" ] 298 ipxsite = "/ipx/" ipx-net ":" ipx-node ":" ipx-socket 299 ipx-net = 8 HEXDIGIT 300 ipx-node = 12 HEXDIGIT 301 ipx-socket = 4 HEXDIGIT 302 atsite = "/at/" at-object ":" at-type "" at-zone 303 at-object = 1*31apple-char 304 at-type = 1*31apple-char 305 at-zone = 1*31apple-char 306 apple-char = ALPHA / DIGIT / safe / escaped 307 = ; AppleAscii [7] values that are not 308 = ; from the restricted range must be escaped. 309 = ; NOTE: The escaped values do NOT correspond 310 = ; to UTF-8 values here: They are AppleAscii 311 = ; bytes. 312 url-part = [ url-path ] [ attr-list ] 313 url-path = 1 * ( "/" *xchar ) 314 ; Each service type must define its 315 ; own syntax consistent 316 ; with [5]. 317 attr-list = 1 * ( ";" attr-asgn ) 318 attr-asgn = attr-id / attr-id "=" attr-value 319 safe = "$" / "-" / "_" / "." / "~" 320 extra = "!" / "*" / "'" / "(" / ")" / "," / "+" 321 uchar = unreserved / escaped 322 xchar = unreserved / reserved / escaped 323 escaped = 1*(`\' HEXDIG HEXDIG) 324 reserved = ";" / "/" / "?" / ":" / "@" / "&" / "=" / "+" 325 unreserved = ALPHA / DIGIT / safe / extra 327 IPX addresses [14] are composed of a network, node and socket number. 328 The IPX network number is a four-byte number, in network order and 329 expressed in hexadecimal, that signifies an IPX subnet. The node 330 element represents a network interface card. It is a six-byte 331 number, expressed in hexadecimal, that is usually the same as the 332 node ID of the interface card. The socket element represents a 333 specific service access point, given an IPX network and node. IPX 334 sockets are analogous to TCP/IP ports, and are not to be confused 335 with Berkeley sockets. 337 AppleTalk addresses [9] are composed of an object, type and zone. 338 The object is a human readable string. The type is an identifier, 339 not intentended for human readability. The zone refers to the 340 AppleTalk Zone name, which is also human readable. The characters 341 composing these names are drawn from the AppleAscii character 342 set [7]. Thus, they do not equate to escaped ASCII or UTF-8 343 characters. The characters "=" and "*" are reserved and may not be 344 included in the names even in binary form. 346 In cases besides the AppleTalk grammar, some characters must be 347 escaped before use. To escape any character, precede the two digits 348 indicating its ASCII value by '%'. 350 2.2. Service URL Semantics 352 The service scheme-specific information following the "service:" 353 URL scheme identifier provides information necessary to access the 354 service. As described in the previous subsection, the form of a 355 service: URL is as follows: 357 service: URL = "service:" service-type ":" site url-path 359 where has one of the following forms could refer to an 360 , or if the service URL locates to an 361 IP, IPX or AppleTalk service access point, respectively. 363 As discussed in Section 1, the can be either a 364 concrete protocol name, or an abstract type name. 366 The field is typically either a domain name (DNS) or an IP 367 network protocol address for the service, and possibly a port number. 368 Note that use of DNS hostnames is preferred for ease of renumbering. 369 The field can be null if other information in the service URL 370 or service attributes is sufficient to use the service. 372 The field allows more information to be provided (by way of 373 and ) that can uniquely locate the service 374 or resource if the is not sufficient for that purpose. For 375 IP addresses, the field begins with "//". Other address 376 families supported are IPX [14] and AppleTalk [9]. 378 An field appears at the end of the field, 379 but is never required to exist in any service location registration. 381 The field is composed of a list of semicolon (";") 382 separated attribute assignments of the form: 384 attr-id "=" attr-value 386 or for keyword attributes: 388 attr-id 390 Attributes are part of service: URLs when the attributes are required 391 to access a particular service. For instance, an ACAP [13] service 392 might require that the client authenticate with it through Kerberos. 393 Including an attribute in the service registration allows the ACAP 394 client to make use of the correct SASL [11] authentication mechanism. 395 The ACAP server's registration might look like: 397 service:acap://some.where.net;authentication=KERBEROSV4 399 Note that there can be other attributes of an ACAP server which 400 are not appropriate to include in the URL. For instance, the list 401 of users who have access to the server is useful for selecting an 402 ACAP server, but is not required for a client to use the registered 403 service. 405 Attributes associated with the service: URL are not typically 406 included in the service: URL. They are stored and retrieved using 407 other mechanisms. The service: URL is uniquely identified with a 408 particular service agent or resource, and is used when registering or 409 requesting the attribute information. The Service Location Protocol 410 specifies how such information is registered by network services and 411 obtained by client software. 413 2.3. Use of service: URLs 415 The service: URL is intended to allow arbitrary client/server and 416 peer to peer systems to make use of a standardized dynamic service 417 access point discovery mechanism. 419 It is intended that service: URLs be selected according to the 420 suitability of associated attributes. A client application can 421 obtain the URLs of several services of the same type and distinguish 422 the most preferable among them by means of their attributes. The 423 client uses the service: URL to communicate directly to a service. 425 Attributes are specified with a formal service template syntax 426 described in Section 3. If a service: URL registration includes 427 attributes, the registering agent SHOULD also keep track of the 428 attributes which characterize the service. 430 Registrations can be checked against the formal attribute 431 specification defined in the template by the client or agent 432 representing the client. Service registration are typically done 433 using the Service Location Protocol [10] (SLP). SLP provides a 434 mechanism for service: URLs to be obtained dynamically, according to 435 the service's attributes. 437 It is also possible to obtain service: URLs from documents and using 438 other protocols. In this case, the URL may not be accompanied by 439 the service attributes. The context in which the URL appears should 440 make it clear, if possible, when the service is appropriate to use. 441 For example, in a mail message, a service might be recommended for 442 use when the user is in a branch office. Or, an HTML document might 443 include a service: URL as a pointer to a service, describing in text 444 what the service does and who is authorized to use it. 446 2.4. Specifying the Service Type-Specific URL Syntax 448 When a service type is specified, the specification includes the 449 definition of the syntax for all URLs that are registered by services 450 of that particular type. For instance, the "lpr" service type may be 451 defined with service: URLs in the following form: 453 service:printer:lpr://
/ 455 The section of the URL after the address of the printer: 457 "/" 459 is specific to the lpr service type and corresponds to the 460 field of the general service: URL syntax. This part is 461 specified when the lpr service type is specified. 463 2.5. Accommodating Abstract Service Types 465 An abstract service type is a service type that can be implemented by 466 a variety of different service agents. 468 In order to register a service: URL for an abstract service type the 469 'abstract-type' grammar rule described in section 3.1 is used. This 470 will result in a URL which includes enough information to use the 471 service, namely, the protocol, address and path information. Unlike 472 'concrete' service: URLs, however, the service type is not enough 473 to determine the service access. Rather, an abstract service type 474 denotes a class of service types. The following subsection discusses 475 this point in more detail. 477 Concrete service templates inherit all attributes defined in the 478 abstract service template from which the concrete service template 479 was derived. Attribute defined in the abstract service template 480 MUST not be defined in the concrete service template as well. This 481 simplifies interpretation of templates. 483 For example, if an abstract service template for service type 484 'Abstract' defines an attribute FOO, all concrete service 485 templates derived from the abstract service template, such as 486 'Abstract:Concrete' will implicitly include the definition of 487 attribute FOO. This derived template MUST NOT redefine FOO, according 488 to the rule above. 490 A further example is described in Section A. 492 2.5.1. Advertising Abstract Service Types 494 Some services may make use of several protocols that are in common 495 use and are distinct services in their own right. In these cases an 496 abstract service type is appropriate. What is essential is that all 497 the required information for the service is clearly defined. 499 For example, suppose a network service is being developed for 500 dynamically loading device drivers. The client requires the 501 following three pieces of information before it can successfully load 502 and instantiate the driver: 504 1. The protocol used to load the driver code, for example, "ftp", 505 "http" or "tftp" 507 2. A pathname identifying where the driver code is located, for 508 example "/systemhost/drivers/diskdrivers.drv", 510 3. The name of the driver, for example, "scsi". 512 The temptation is to form the first two items into a URL and embed 513 that into a service: URL. As an example which should be avoided, 515 service:ftp:/x3.bean.org/drivers/diskdrivers.drv;driver=scsi 517 is a service: URL which seems to indicate where to obtain the driver. 519 Rather, an abstract service-type SHOULD be used. The service type is 520 not "ftp", as the example indicates. Rather, it is "device-drivers". 521 The service: URL that should be used, consistent with the rules in 522 section [6], is the following: 524 service:device-drivers:ftp://x3.bean.org/drivers/diskdrivers.drv; 525 driver=scsi;platform=sys3.2-rs3000 527 Other URLs for the same service using other protocols are also 528 supported, as in: 530 service:device-drivers:tftp://x2.bean.org/vol3/disk/drivers.drv; 531 driver=scsi;platform=sys3.2-rs3000 533 service:device-drivers:http://www.bean.org/drivers/drivpak.drv; 534 driver=scsi;platform=sys3.2-rs3000 536 Using SLP, a search for the service type "device-drivers" may return 537 all of the three URLs listed above. The client selects the most 538 appropriate access protocol for the desired resource. 540 The fundamental requirement is that the abstract service type MUST 541 be well specified. This requirement is imposed so that program code 542 or human users have enough information to access the service. In 543 every case, a well-specified abstract type will include either an 544 access protocol and a network address where the service is available, 545 or an embedded URL for a standardized URL scheme that describes 546 how to access the service. In the example above, there are three 547 further requirements: A URL path is included for access protocols 548 indicating the document to download, and two attributes are included 549 to characterize the driver. 551 3. Syntax and Semantics of Service Type Specifications 553 Service type specifications are documents in a formal syntax defining 554 properties important to service registration. These properties are: 556 1. General information on the service type specification itself, 558 2. The syntax of the service type-specific part of the service URL, 560 3. The definition of attributes associated with a service. 562 The service type specification document is the service type template. 564 The following subsections describe the syntax and semantics of 565 service type templates. 567 3.1. Syntax of Service Type Templates 569 Service template documents are encoded in a simple form. They may 570 be translated into any language or character set, but the template 571 used for standardization MUST be encoded in the 0x00-0x7F subrange of 572 UTF-8 [16] (which corresponds to ASCII character encoding) and be in 573 English. 575 A template document begins with a block of text assigning values to 576 five document identification items. The five identification items 577 can appear in any order within the block, but conventionally the 578 "template-type" item, which assigns the service type name, occurs at 579 the very top of the document in order to provide context for the rest 580 of the the document. The attribute definition item occurs after the 581 document identification items. 583 All items end with a blank line. The reserved characters are ";", 584 "%", "=", ",", "#", LF, and CR. Reserved characters MUST be escaped. 585 The escape sequence is the same as described in [5]. 587 The service template is encoded in a UTF-8 character set, but 588 submitted as a part of an internet-draft, which is encoded in 589 ASCII characters. All characters which are outside of the ASCII 590 range MUST be escaped using the `\' HEXDIG HEXDIG syntax. For 591 example, the letter e accent aigue would be represented as "\c3\a9". 592 Unfortunately, this will detract from the readability of the service 593 template in the service template submission. Hopefully some public 594 domain tools will emerge for translating escaped UTF-8 characters 595 into humanly readable ones. 597 Values in value lists are separated by commas. A value list is 598 terminated by a newline not preceded by a comma. If the newline is 599 preceded by a comma, the value list is interpreted to continue onto 600 the next line. 602 Attribute identifiers, attribute type names, and flags are all 603 case insensitive. For ease of presentation, upper and lower case 604 characters can be used to represent these in the template document. 605 Newlines are significant in the grammar. They delimit one item from 606 another, as well as separating parts of items internally. 608 String values are considered to be a sequence of non-whitespace 609 tokens potentially with embedded whitespace, separated from each 610 other by whitespace. Commas delimit lists of strings. String values 611 are trimmed so as to reduce any sequence of white space interior to a 612 string to a single white space. Preceding or trailing white space is 613 removed. For example: 615 " some value , another example " 617 is trimmed to 619 "some value" and "another example". 621 Note that there can be no ambiguity in string tokenization because 622 values in value lists are separated by a comma. String tokens are 623 not delimited by double quotes (") as is usually the case with 624 programming languages. 626 Attribute tags and values are useful for directory look-up. In this 627 case, decoding of character escapes and trimming white space MUST 628 be performed before string matching. In addition, string matching 629 SHOULD be case insensitive. 631 Templates obey the following ABNF [8] grammar: 633 template = tem-attrs attr-defs 634 tem-attrs = schemetype schemevers schemetext schemeurl 635 schemetype = "template-type=" scheme term 636 schemevers = "template-version=" version-no term 637 schemetext = "template-description=" newline desc term 638 schemeurl = "template-url-syntax=" newline url-bnf term 639 url-bnf = *[ com-chars ] 640 ; An ABNF describing the production 641 ; in the service: URL grammar of Section 2.1. 642 scheme = service-type [ "." naming-auth ] 643 service-type = scheme-name 644 naming-auth = scheme-name 645 scheme-name = ALPHA [1*schemechar] [ "." 1*schemechar ] 646 schemechar = ALPHA / DIGIT / "-" / "+" / 647 version-no = 1*DIGIT "." 1*DIGIT 648 langtag = 1*8ALPHA ["-" 1*8ALPHA] 649 ; See [3] 650 desc = *[ com-chars ] 651 ; A block of free-form text for reading by 652 ; people describing the service in a short, 653 ; informative manner. 654 term = newline newline 655 attr-defs = *( attr-def / keydef ) 656 attr-def = id "=" attrtail 657 keydef = id "=" "keyword" newline [help-text] newline 658 attrtail = type flags newline [value-list] [help-text] 659 [value-list] newline 660 id = 1*attrchar 661 type = "string" / "integer" / "boolean" / "opaque" 662 flags = ["m"/"M"] ["l"/"L"] ["o"/"O"] ["x"/"X"] 663 value-list = value newline / value "," value-list / 664 value "," newline value-list 665 help-text = 1*( "#" help-line ) 666 ; A block of free-form text for reading by 667 ; people describing the attribute and 668 ; its values. 670 help-line = *[ com-chars ] newline 671 attrchar = schemechar / ":" / "_" / "$" / "~" / "@" / "." / 672 "|" / "<" / ">" / "*" / "&" 673 value = string / integer / boolean / opaque 674 string = safe-char *[safe-char / white-sp] safe-char 675 integer = [ "+" | "-" ] 1*DIGIT 676 boolean = "true" / "false" 677 opaque = "\FF" 1*( "\" HEXDIG HEXDIG) 678 ; Each byte of opaque value is hex encoded. 679 ; The format corresponds to [10]. 680 ; Newlines are ignored in decoding opaque 681 ; values. 682 com-chars = safe-char / white-sp / "," / ";"/ "%" 683 safe-char = attrchar / escaped / " " / "!" / '"' / "'" / 684 "|" / "(" / ")" / "+" / "-" / "." / ":" / 685 "=" / "?" / "[" / "]" / "{" / "/" / "{" / 686 "$" 687 ; All UTF-8 printable characters are 688 ; included except ",", "%", ";", and "#". 689 escaped = 1*(`\' HEXDIG HEXDIG) 690 white-sp = SPACE / HT 691 newline = CR / ( CR LF ) 693 3.2. Semantics of Service Type Templates 695 The service type template defines the service attributes and service: 696 URL syntax for a particular service type. The attribute definition 697 includes the attribute type, default values, allowed values and other 698 information. 700 Note that the 'template-type', 'template-version', 701 'template-description' and 'template-url-syntax' have all been 702 defined as attributes. These attributes MAY accompany any service 703 registration using SLPv2. 705 3.2.1. Definition of a Service Template 707 There are four items included in the service template. The semantics 708 of each item is summarized below. 710 - template-type 712 The scheme name of the service scheme. The scheme name consists 713 of the service type name and an optional naming authority name, 714 separated from the service type name by a period. See 3.2.2 for 715 the conventions governing service type names. 717 - template-version 719 The version number of the service type specification. 721 - template-description 723 A description of the service suitable for inclusion in text read 724 by people. 726 - template-url-syntax 728 The syntax of the service type-specific URL part of the service: 729 URL. 731 - attribute definitions 733 A collection of zero or more definitions for attributes 734 associated with the service in service registrations. 736 Each of the following subsections deals with one of these items. 738 3.2.2. Service Type 740 The service scheme consists of the service type name and an optional 741 naming authority name separated from the service type name by 742 a period. The service scheme is a string that is appended to 743 the 'service:' URL scheme identifier, and is the value of the 744 "template-type" item in the template document. If the naming 745 authority name is absent it is assumed to be IANA. 747 3.2.3. Version Number 749 The version number of the service type template is the value of the 750 "template-version" item. A draft proposal starts at 0.0, and the 751 minor number increments once per revision. A standardized template 752 starts at 1.0. Additions of optional attributes add one to the minor 753 number, and additions of required attributes, changes of definition, 754 or removal of attributes add one to the major number. The intent 755 is that an old service template still accurately, if incompletely, 756 defines the attributes of a service registration if the template only 757 differs from the registration in its minor version. See Section 4 758 for more detail on how to use the template-version attribute. 760 3.2.4. Description 762 The description is a block of text readable by people in the language 763 of the template and is the value of the "template-description" item. 764 It should be sufficient to identify the service to human readers and 765 provide a short, informative description of what the service does. 767 If the service type corresponds to a particular protocol, the 768 protocol specification must be cited here. The protocol need not be 769 a standardized protocol. The template might refer to a proprietary 770 specification, and refer the reader of the template to a contact 771 person for further information. 773 3.2.5. Syntax of the Service Type-specific URL Part 775 The syntax of the service type-specific part of the service: 776 URL is provided in the template document as the value of the 777 "template-url-syntax" item. The field of the service: 778 URL is designed to provide additional information to locate a service 779 when the field is not sufficient. The field 780 distinguishes URLs of a particular service type from those of another 781 service type. For instance, in the case of the lpr service type, the 782 may be defined so that it must include the queue name, 783 but other service types may not require this information. 785 The syntax for the field MUST accompany the definition 786 of a new service type, unless the URL scheme has already been 787 standardized and is not a service: URL. The syntax is included in the 788 template document as an ABNF [8] following the rules for URL syntax 789 described in [5]. There is no requirement for a service scheme to 790 support a . The field can be very simple, 791 or even omitted. If the URL scheme has already been standardized, 792 the "template-url-syntax" item SHOULD include a reference to the 793 appropriate standardization documents. Abstract service types may 794 defer this field to the template documents describing their concrete 795 instances. 797 3.2.6. Attribute Definition 799 The bulk of the template is typically devoted to defining service 800 type-specific attributes. An attribute definition precisely 801 specifies the attribute's type, other restrictions on the attribute 802 (whether it is multi-valued, optional, etc), some text readable by 803 people describing the attribute, and lists of default and allowed 804 values. The only required information is the attribute's type, the 805 rest are optional. Registration, deregistration and the use of 806 attributes in queries can be accomplished using the Service Location 807 Protocol [10] or other means, and discussion of this is beyond the 808 scope of the document. 810 Attributes are used to convey information about a given service for 811 purposes of differentiating different services of the same type. 812 They convey information to be used in the selection of a particular 813 service to establish communicate with, either through a program 814 offering a human interface or programmatically. Attributes can be 815 encoded in different character sets and in different languages. The 816 procedure for doing this is described in Section 6. 818 An attribute definition begins with the specification of the 819 attribute's identifier and ends with a single empty line. Attributes 820 definitions have five components (in order of appearance in a 821 definition): 823 1. An attribute identifier which acts as the name of the attribute, 825 2. Attribute descriptors (type and flags), 827 3. An optional list of values which are assigned to the attribute by 828 default, 830 4. An optional block of text readable by people providing a short, 831 informative description of the attribute, 833 5. An optional list of allowed values which restrict the value or 834 values the attribute can take on. 836 3.2.6.1. The Attribute Identifier 838 An attribute definition starts with the specification of the 839 attribute's identifier. The attribute's identifier functions as the 840 name of the attribute. Note that the characters used to compose an 841 attribute identifier are restricted to those characters considered 842 unrestricted for inclusion in a URL according to [5]. The reason 843 is that services can display prominent attributes in their service: 844 URL registrations. Each attribute identifier must be unique in the 845 template. Since identifiers are case folded, upper case and lower 846 case characters are the same. 848 3.2.6.2. The Attribute Type 850 Attributes can have one of five different types: string, integer, 851 boolean, opaque, or keyword. The attribute's type specification is 852 separated from the attribute's identifier by an equal sign ("=") and 853 follows the equal sign on the same line. The string, signed integer, 854 and boolean types have the standard programming language or database 855 semantics. Integers are restricted to those signed values that can 856 be represented in 32 bits. The character set used to represent 857 strings is not specified at the time the template is defined, but 858 rather is determined by the service registration. Booleans have the 859 standard syntax. Opaques are byte escaped values that can be used 860 to represent any other kind of data. Keywords are attributes that 861 have no characteristics other than their existence (and possibly the 862 descriptive text in their definition). 864 Keyword and boolean attributes impose restrictions on the following 865 parts of the attribute definition. Keyword attribute definitions 866 MUST have no flag information following the type definition, nor any 867 default or allowed values list. Boolean attributes are single value 868 only, i.e., multi-valued boolean attributes are not allowed. 870 3.2.6.3. Attribute Flags 872 Flags determine other characteristics of an attribute. With the 873 exception of keyword attributes, which may not have any flags, 874 flags follow the attribute type on the same line as the attribute 875 identifier, and are separated from each other by whitespace. Flags 876 may appear in any order after the attribute type. Other information 877 must not follow the flags, and only one flag identifier of a 878 particular flag type is allowed per attribute definition. 880 The semantics of the flags are as follows: 882 - o or O 884 Indicates that the attribute is optional. If this flag is 885 missing, the attribute is required in every service registration. 887 - m or M 889 Indicates that the attribute can take on multiple values. If 890 this flag is present, every value in a multi-valued attribute 891 has the same type as the type specified in the type part of the 892 attribute definition. Boolean attributes must not include this 893 flag. 895 - l or L 897 Indicates that attribute is literal, i.e. is not meant to be 898 translated into other languages. If this flag is present, the 899 attribute is not considered to be readable by people and should 900 not be translated when the template is translated. See Section 6 901 for more information about translation. 903 - x or X 905 Indicates that clients SHOULD include the indicated attribute 906 in requests for services. Neglecting to include this attribute 907 will not sufficiently differentiate the service. If services are 908 obtained without selecting this attribute they will quite likely 909 be useless to the client. 911 The values for multivalued attributes are an unordered set. 912 Deletions of individual values from a multivalued attribute are not 913 supported, and deletion of the attribute causes the entire set of 914 values to be removed. 916 3.2.6.4. Default Value or List 918 If the attribute definition includes a default value or, in the 919 case of multivalued attributes, a default values list, it begins 920 on the second line of the attribute definition and continues 921 over the following lines until a line ends without a comma. As a 922 consequence, newlines cannot be embedded in values unless escaped. 923 See Section 2.1. 925 Particular attribute types and definitions restrict the default 926 values list. Keyword attributes must not have a list of defaults. 927 If an optional attribute's definition has an allowed values list, 928 then a default value or list is not optional but required. The 929 motivation for this is that defining an attribute with an allowed 930 values list is meant to restrict the values the attribute can take 931 on, and requiring a default value or list assures that the default 932 value is a member of the given set of allowed values. 934 The default value or list indicates what values the attribute is 935 given if no values are assigned to the attribute when a service 936 is registered. If an optional attribute's definition includes no 937 default value or list, the following defaults are assigned: 939 1. String values are assigned the empty string, 941 2. Integer values are assigned zero, 943 3. Boolean values are assigned false, 945 4. Opaque values are assigned a byte array containing no values, 947 5. Multi-valued attributes are initialized with a single value. 949 For purposes of translating nonliteral attributes, the default values 950 list is taken to be an ordered set, and translations MUST maintain 951 that order. 953 3.2.6.5. Descriptive Text 955 Immediately after the default values list, if any, a block of 956 descriptive text SHOULD be included in the attribute definition. 957 This text is meant to be readable by people, and should include 958 a short, informative description of the attribute. It may also 959 provide additional information, such as a description of the allowed 960 values. This text is primarily designed for display by interactive 961 browsing tools. The descriptive text is set off from the surrounding 962 definition by a crosshatch character ("#") at the beginning of 963 the line. The text should not, however, be treated as a comment 964 by parsing and other tools, since it is an integral part of the 965 attribute definition. Within the block of descriptive text, the text 966 is transferred verbatim, including indentation and line breaks, so 967 any formatting is preserved. 969 3.2.6.6. Allowed Values List 971 Finally, the attribute definition concludes with an optional 972 allowed values list. The allowed values list, if any, follows the 973 descriptive text, or, if the descriptive text is absent, the initial 974 values list. The syntax of the allowed values list is identical to 975 that of the initial values list. The allowed values list is also 976 terminated by a line that does not end in a comma. If the allowed 977 values list is present, assignment to attributes is restricted to 978 members of the list. 980 As with the default values list, the allowed values list is also 981 considered to be an ordered set for purposes of translation. 983 3.2.6.7. Conclusion of An Attribute Definition 985 An attribute definition concludes with a single empty line. 987 4. A Process For Standardizing New Service Types 989 New service types can be suggested simply by providing a service type 990 template and a short description about how to use the service. The 991 template MUST have its "template-version" template attribute set to 992 0.0. 994 MAJOR revision numbers come before the '.', MINOR revision numbers 995 come after the '.'. 997 The minor version number increments once with each change until it 998 achieves 1.0. There is no guarantee any version of the service 999 template is backward compatible before it reaches 1.0. 1001 Once a service template has reached 1.0, the definition is "frozen" 1002 for that version. New templates must be defined, of course, to 1003 refine that definition, but the following rules must be followed: 1005 A MINOR revision number signifies the introduction of a compatible 1006 change. A MAJOR revision number signifies the introduction of an 1007 incompatible change. This is formalized by the following rules: 1009 - Any new optional attribute defined for the template increases 1010 the minor version number by one. All other attributes for the 1011 version must continue to be supported as before. A client which 1012 supports 1.x can still use later versions of 1.y (where x "." "." 1082 Each of these fields are defined in Section 2. They correspond to 1083 the values of the template fields "type", "template-version". The 1084 files for the example templates in this document (see Section A) are 1085 called: 1087 "foo.0.0.en", 1088 "Net-Transducer.0.0.en", 1089 "Net-Transducer:Thermometer.0.0.de" and 1090 "Net-Transducer:Thermomoter.0.0.en". 1092 The reviewer will ensure that the template submission to IANA has the 1093 correct form and required fields. 1095 No service type template will be accepted for inclusion in the 1096 service template registry unless the submission includes a security 1097 considerations section and contact information for the template 1098 document author. 1100 The IANA will maintain a registry containing both the service type 1101 templates, and the template description document containing the 1102 service type template, including all previous versions. The IANA 1103 will receive notice to include a service template in the registry 1104 by email from the reviewer. This message will include the service 1105 template itself, which is to be registered. 1107 Neither the reviewer nor the IANA will take any position on claims of 1108 copyright or trademark issues with regard to templates. 1110 6. Internationalization Considerations 1112 The service: URL must be encoded using the rules set forth in [5]. 1113 The character set encoding is limited to specific ranges within the 1114 US-ASCII character set [4]. 1116 The template is encoded in UTF-8 characters. 1118 6.1. Language Identification and Translation 1120 The language used in attribute strings should be identified 1121 supplying a Language Tag [3] in the Service Template submission (see 1122 Section 5). 1124 A program can translate a service registration from one language to 1125 another provided it has both the template of the language for the 1126 registration and the template of the desired target language. All 1127 standardized attributes are in the same order in both templates. 1128 All non-arbitrary strings, including the descriptive help text, is 1129 directly translatable from one language to another. Non-literal 1130 attribute definitions, attribute identifiers, attribute type names, 1131 attribute flags, and the boolean constants "true" and "false" are 1132 never translated. Translation of attribute identifiers is prohibited 1133 because, as with domain names, they can potentially be part of a 1134 service: URL and therefore their character set is restricted. In 1135 addition, as with variable identifiers in programming languages, they 1136 could become embedded into program code. 1138 All strings used in attribute values are assumed translatable unless 1139 explicitly defined as being literal, so that best effort translation 1140 (see below) does not modify strings which are meant to be interpreted 1141 by a program, not a person. 1143 An example of a translated service template is included in Section A. 1145 There are two ways to go about translation: standardization and best 1146 effort. 1148 When the service type is standardized, more than one document can 1149 be submitted for review. One service type description is approved 1150 as a master, so that when a service type template is updated in one 1151 language, all the translations (at least eventually) reflect the same 1152 semantics. 1154 If no document exists describing the standard translation of the 1155 service type, a 'best effort' translation for strings should be done. 1157 7. Security Considerations 1159 Service type templates provide information that is used to interpret 1160 information obtained by the Service Location Protocol. If these 1161 templates are modified or false templates are distributed, services 1162 may not correctly register themselves, or clients might not be able 1163 to interpret service information. 1165 The service: URLs themselves specify the service access point and 1166 protocol for a particular service type. These service: URLs could 1167 be distributed and indicate the location of a service other than 1168 that normally want to used. The Service Location Protocol [10] 1169 distributes service: URLs and has an authentication mechanism that 1170 allows service: URLs of registered services to be signed and for the 1171 signatures to be verified by clients. 1173 Each Service Template will include a security considerations section 1174 which will describe security issues with using the service scheme for 1175 the specific Service Type. 1177 A. Service Template Examples 1179 The text in the template example sections is to be taken as being a 1180 single file. They are completely fictitious (ie. the examples do 1181 not represent real services). 1183 The FOO example shows how to use service templates for an application 1184 that has very few attributes. Clients request the FOO server where 1185 their user data is located by including their user name as the value 1186 of the user attribute. 1188 The Net-Transducer example shows how abstract service types are 1189 defined and how a corresponding concrete instance is defined. A 1190 system might support any of several NetTransducer services. Here we 1191 give only one concrete instance of the abstract type. 1193 It is not necessary to register concrete templates for an abstract 1194 service type if the abstract service type template is completely 1195 clear as to what possible values can be used as a concrete type, and 1196 what their interpretation is. 1198 A.1. FOO 1200 The FOO service template submission example follows: 1202 Name of submitter: "Erik Guttman" 1203 Language of service template: en 1204 Security Considerations: 1205 If the USER and GROUPS attributes are included a 1206 possibility exists that the list of identities for users or groups 1207 can be discovered. This information would otherwise be difficult 1208 to discover. 1209 Template Text: 1210 -------------------------template begins here----------------------- 1211 template-type=FOO 1213 template-version=0.0 1215 template-description= 1216 The FOO service URL provides the location of an FOO service. 1218 template-url-syntax= 1219 url-path= ; There is no URL path defined for a FOO URL. 1221 users= string M L O 1222 # The list of all users which the FOO server supports. 1224 groups= string M L O 1225 # The list of all groups which the FOO server supports. 1226 --------------------------template ends here------------------------ 1228 This template could be internationalized by registering another 1229 version, say in German: 1231 Name of submitter: "Erik Guttman" 1232 Language of service template: de 1233 Security Considerations: 1234 Wenn die USER und GROUPS Eigenschaften inbegriffen sind, 1235 besteht die Moeglichkeit, dass die Liste der Identitaeten 1236 von Benutzern oder Gruppen endeckt verden kann. Diese 1237 Information wurde unter anderen Umstaenden schwierig zu 1238 entdecken sein. 1240 Template Text: 1241 -------------------------template begins here----------------------- 1242 template-type=FOO 1244 template-version=0.0 1246 template-description= 1247 Der FOO Service URL zeigt die Stelle von einem Foo Service an. 1249 template-url-syntax= 1250 url-path= ; Es gibt keinen fuer den FOO URL definierten Pfad. 1252 users= string M L O 1253 # Die Liste aller Users, die der FOO Server unterstuetzt. 1255 groups= string M L O 1256 # Die Liste aller Gruppen, die der FOO Server unterstuetzt. 1257 --------------------------template ends here------------------------ 1259 Note that the attribute tags are not translated. If translations 1260 are desired, the suggested convention for doing so is to define a 1261 separate attribute called localize- for each attribute tag which 1262 is to be localized. This will aid in displaying the attribute tags 1263 in a human interface. 1265 For example, in this case above, the following two attributes could 1266 be defined: 1268 localize-users= string 1269 Benutzer 1271 localize-groups= string 1272 Gruppen 1274 The attributes (in SLPv2 attribute list format) for a service 1275 registration of a FOO service based on this template, in German, 1276 could be: 1278 (users=Hans,Fritz),(groups=Verwaltung,Finanzbuchhaltung), 1279 (template-type=FOO),(template-version=0.0),(template-description= 1280 Der FOO Service URL zeigt die Stelle von einem Foo Service an.), 1281 (template-url-syntax= \OD url-path= ; Es gibt kein fuer den FOO 1282 URL definiert Pfad. \OD),(localize-users=Benutzer), 1283 (localize-groups=Gruppen) 1285 Anyone obtaining these attributes could display "Benutzer=Hans,Fritz" 1286 in a human interface using the included information. Note that the 1287 template attributes have been included in this registration. This is 1288 OPTIONAL, but makes it possible to discover which template was used 1289 to register the service. 1291 A.2. Abstract Service Type: Net-Transducer 1293 An example submission of an abstract service type template is: 1295 Name of submitter: "Erik Guttman" 1296 Language of service template: en 1297 Security Considerations: 1298 See the security considerations of the concrete service types. 1299 Template Text: 1300 -------------------------template begins here----------------------- 1301 template-type=Net-Transducer 1303 template-version=0.0 1305 template-description= 1306 This is an abstract service type. The purpose of the Net- 1307 Transducer service type is to organize into a single category 1308 all network enabled Transducers which have certain properties. 1310 template-url-syntax= 1311 url-path= ; Depends on the concrete service type. 1312 ; See these templates. 1314 sample-units= string L 1315 # The units of sample that the Transducer provides, for instance 1316 # C (degrees Celsius), V (Volts), kg (Kilograms), etc. 1318 sample-resolution= string L 1319 # The resolution of the Transducer. For instance, 10^-3 means 1320 # that the Transducer has resolution to 0.001 unit. 1322 sample-rate= integer L 1323 # The speed at which samples are obtained per second. For 1324 # instance 1000 means that one sample is obtained every millisecond. 1326 --------------------------template ends here------------------------ 1328 A.3. Concrete Service Type: Net-Transducer:Thermometer 1330 This is another service template submission example, supplying a 1331 concrete service type corresponding to the abstract template above. 1333 Name of submitter: "Erik Guttman" 1334 Language of service template: en 1335 Security Considerations: 1336 There is no authentication of the Transducer output. Thus, 1337 the Thermometer output could easily be spoofed. 1338 Template Text: 1339 -------------------------template begins here----------------------- 1340 template-type=service:Net-Transducer:Thermometer 1342 template-version=0.0 1344 template-description= 1345 The Thermometer is a Net-Transducer capable of reading temperature. 1346 The data is read by opening a TCP connection to one of the ports 1347 in the service URL and reading an ASCII string until an NULL 1348 character is encountered. The client may continue reading data at 1349 no faster than the sample-rate, or close the connection. 1351 template-url-syntax= 1352 url-path = "ports=" ports-list 1353 port-list = port / port "," ports 1354 port = 1*DIGIT 1355 ; See the Service URL production rule. 1356 ; These are the ports connections can be made on. 1358 location-description=string 1359 # The location where the Thermometer is located. 1361 operator=string O 1362 # The operator to contact to have the Thermometer serviced. 1364 --------------------------template ends here------------------------ 1366 A.4. service: URLs and SLP 1368 A user with an FOO enabled calendar application should not be 1369 bothered with knowing the address of their FOO server. The 1370 calendar client program can use SLP to obtain the FOO service: URL 1371 automatically, say 'service:foo://server1.nosuch.org', by issuing 1372 a Service Request. In the event that this FOO server failed, the 1373 Calendar client can issue the same service request again to find the 1374 backup FOO server, say 'service:foo://server2.nosuch.org'. In both 1375 cases, the service: URL conforms to the FOO service template as do 1376 the associated attributes (user and group.) 1378 A network thermometer based on the above template could be advertised 1379 with the SLPv2 attribute list: 1381 URL = service:net-transducer:thermometer://v33.test/ports=3211 1382 Attributes = (location-description=Missile bay 32), 1383 (operator=Joe Agent), (sample-units=C), 1384 (sample-resolution=10^-1),(sample-rate=10), 1385 (template-type=service:net-transducer:thermometer), 1386 (template-version=0.0),(template-description= 1387 The Thermometer is a Net-Transducer capable of reading temperature. 1388 The data is read by opening a TCP connection to one of the ports 1389 in the service URL and reading an ASCII string until an NULL 1390 character is encountered. The client may continue reading data at 1391 no faster than the sample-rate, or close the connection.), 1392 (template-url-syntax= \0D "ports=" port-list \OD 1393 port-list = port / port "," ports \OD 1394 port = 1*DIGIT \OD 1395 ; See the Service URL production rule. \OD 1396 ; These are the ports connections can be made on.\OD) 1398 This might be very useful for a technician who wanted to find a 1399 Thermometers in Missile bay 32, for example. 1401 Note that the template attributes are advertised. The 1402 template-url-syntax value requires explicit escaped CR characters so 1403 that the ABNF syntax is correct. 1405 B. Full Copyright Statement 1407 Copyright (C) The Internet Society (1997). All Rights Reserved. 1409 This document and translations of it may be copied and furnished to 1410 others, and derivative works that comment on or otherwise explain it 1411 or assist in its implmentation may be prepared, copied, published 1412 and distributed, in whole or in part, without restriction of any 1413 kind, provided that the above copyright notice and this paragraph 1414 are included on all such copies and derivative works. However, 1415 this document itself may not be modified in any way, such as by 1416 removing the copyright notice or references to the Internet Society 1417 or other Internet organizations, except as needed for the purpose 1418 of developing Internet standards in which case the procedures 1419 for copyrights defined in the Internet Standards process must be 1420 followed, or as required to translate it into languages other than 1421 English. 1423 The limited permissions granted above are perpetual and will not be 1424 revoked by the Internet Society or its successors or assigns. 1426 This document and the information contained herein is provided on an 1427 "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING 1428 TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING 1429 BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION 1430 HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF 1431 MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE." 1433 C. Acknowledgments 1435 Thanks to Michael Day and Leland Wallace for assisting with the IPX 1436 and AppleTalk address syntax portions. Ryan Moats provided valuable 1437 feedback throughout the writing of this document. 1439 References 1441 [1] Protocol and service names, October 1994. 1442 ftp://ftp.isi.edu/in-notes/iana/assignments/service-names. 1444 [2] Port numbers, July 1997. 1445 ftp://ftp.isi.edu/in-notes/iana/assignments/port-numbers. 1447 [3] H. Alvestrand. Tags for the Identification of Languages. RFC 1448 1766, March 1995. 1450 [4] ANSI. Coded Character Set -- 7-bit American Standard code for 1451 Information Interchange. X3.4-1986, 1986. 1453 [5] T. Berners-Lee, R. Fielding, and L. Masinter. Uniform Resource 1454 Identifiers (URI): Generic Syntax. RFC 2396, August 1998. 1456 [6] S. Bradner. Key Words for Use in RFCs to Indicate Requirement 1457 Levels. RFC 2119, March 1997. 1459 [7] Apple Computer. Inside Macintosh. Addison-Wesley, 1993. 1461 [8] D. Crocker and P. Overell. Augmented BNF for Syntax 1462 Specifications: ABNF. RFC 2234, November 1997. 1464 [9] S. Gursharan, R. Andrews, and A. Oppenheimer. Inside AppleTalk. 1465 Addison-Wesley, 1990. 1467 [10] E. Guttman, C. Perkins, J. Veizades, and M. Day. Service 1468 Location Protocol version 2. draft-ietf-svrloc-protocol-v2-04.txt, 1469 March 1998. (work in progress). 1471 [11] J. Myers. Simple Authentication and Security Layer (SASL). RFC 1472 2222, October 1997. 1474 [12] T. Narten and H. Alvestrand. RFC 2434: Guidelines for writing 1475 an IANA considerations section in RFCs, October 1998. Status: 1476 BEST CURRENT PRACTICE. 1478 [13] C. Newman and J. G. Myers. ACAP -- Application Configuration 1479 Access Prototol. RFC 2244, November 1997. 1481 [14] Inc Novell. IPX RIP and SAP Router Specification. Part Number 1482 107-000029-001, Version 1.30, May 1996. 1484 [15] J. Veizades, E. Guttman, C. Perkins, and S. Kaplan. Service 1485 Location Protocol. RFC 2165, July 1997. 1487 [16] F. Yergeau. UTF-8, a transformation format of ISO 10646. RFC 1488 2279, January 1998. 1490 Authors' Addresses 1492 Questions about this memo can be directed to: 1494 Erik Guttman Charles E. Perkins James Kempf 1495 Sun Microsystems Sun Microsystems Sun Microsystems 1496 Bahnstr. 2 15 Network Circle 15 Network Circle 1497 74915 Waibstadt Menlo Park, CA 94303 Menlo Park, CA 94303 1498 Germany USA USA 1499 +49 7263 911484 +1 650 786 6464 +1 650 786 5890 1500 +1 650 786 5992 +1 650 786 6445 (fax) +1 650 786 6445 (fax) 1501 erik.guttman@sun.com cperkins@sun.com james.kempf@sun.com