Service Location Working Group Erik Guttman INTERNET DRAFT Charles Perkins 6 June 1997 Sun Microsystems Service Templates and service: Schemes draft-ietf-svrloc-service-scheme-01.txt Status of This Memo This document is a submission by the Service Location Working Group of the Internet Engineering Task Force (IETF). Comments should be submitted to the srvloc@corp.home.net mailing list. Distribution of this memo is unlimited. This document is an Internet-Draft. Internet-Drafts are working documents of the Internet Engineering Task Force (IETF), its areas, and its working groups. Note that other groups may also distribute working documents as Internet-Drafts. Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as ``work in progress.'' To learn the current status of any Internet-Draft, please check the ``1id-abstracts.txt'' listing contained in the Internet-Drafts Shadow Directories on ftp.is.co.za (Africa), nic.nordu.net (North Europe), ftp.nis.garr.it (South Europe), munnari.oz.au (Pacific Rim), ds.internic.net (US East Coast), or ftp.isi.edu (US West Coast). Abstract Service: schemes define URLs (called "service: URLs" in this document) which are primarily intended to be used by the Service Location Protocol in order to distribute service access information. These schemes provide an extensible framework for client based network software to obtain configuration information required to make use of network services. When registering a service: URL with a Directory Agent, the URL may be accompanied by a set of well defined attributes which define the charateristics of the service. These attributes may convey configuration information to client software, or service characteristics meaningful to end users. This document describes how to define and standardize new service types and attributes for use with the service: scheme using Service Guttman,Perkins Expires 6 December 1997 [Page i] Internet Draft Service Templates and URLs 6 June 1997 Templates. These templates are human and machine readable. They may be used by administrative tools to parse service registration information and by client applications to provide localized translations of service attribute strings. Guttman,Perkins Expires 6 December 1997 [Page ii] Internet Draft Service Templates and URLs 6 June 1997 Contents Status of This Memo i Abstract i 1. Introduction 2 1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 3 1.2. Service Schemes . . . . . . . . . . . . . . . . . . . . . 4 1.3. Related work . . . . . . . . . . . . . . . . . . . . . . 5 1.4. Changes made since the last version . . . . . . . . . . . 5 1.5. Open issues and work to be done . . . . . . . . . . . . . 6 2. Use of service: URLs 6 3. Specifying A New Service Type 7 3.1. Service Type Specifications . . . . . . . . . . . . . . . 7 3.1.1. Service Type . . . . . . . . . . . . . . . . . . 7 3.1.2. The service: 'url-path' information . . . . . . 8 3.1.3. Attributes . . . . . . . . . . . . . . . . . . . 8 3.2. Specifying Attributes . . . . . . . . . . . . . . . . . . 8 3.2.1. Service Templates and attributes . . . . . . . . 9 3.2.2. Service Templates String Encoding . . . . . . . . 9 3.2.3. Attributes with multiple values . . . . . . . . . 12 3.2.4. Grouping attribute values together in records . . 12 3.3. Special attributes . . . . . . . . . . . . . . . . . . . 13 3.3.1. Service Type Language . . . . . . . . . . . . . . 13 3.3.2. Version . . . . . . . . . . . . . . . . . . . . . 13 3.3.3. url-path rules . . . . . . . . . . . . . . . . . 14 4. A Process For Standardizing New Service Types 14 5. Encoding Rules for Service Type URLs 15 6. Examples 16 6.1. SLP Directory Agent . . . . . . . . . . . . . . . . . . . 16 6.2. POP3 . . . . . . . . . . . . . . . . . . . . . . . . . . 16 7. General Service Template 17 7.1. Obtaining Service Templates dynamically . . . . . . . . . 18 8. Internationalization Considerations 18 8.1. Character Set identification and use . . . . . . . . . . 18 8.2. Language identification and translation . . . . . . . . . 19 Guttman,Perkins Expires 6 December 1997 [Page 1] Internet Draft Service Templates and URLs 6 June 1997 9. Security Considerations 19 1. Introduction This document describes a class of schemes which will allow network services to define their service access information, using a standard notation. In addition it describes how to define a set of attributes to associate with a service: URL. These attributes will allow end users and programs to select between network services of the same type that have different capabilities. A client may use these attributes to select a particular service (obtain the service: URL) that has the configuration it needs. The minimal encoding rules for attributes are specified. Service Type templates are used to describe in a standard way those services which use the service: URL. The rules for specifying a scheme are provided, along with two examples. Templates are used the following distinct purposes: 1. Standardization The template is reviewed before it is standardized. Once it is standardized, all versions of the template are archived by IANA. 2. Service Registration Servers making use of the Service Location Protocol will register themselves and their attributes. They will use the templates to generate the service registrations; the service must pick from among the allowable values. 3. Client presentation of Service Information Client applications may display service information. The template provides type information and explanatory text which may be helpful in producing user interfaces. 4. Internationalization If a client application has the template for a given service type in two different languages, the attributes may be translated back and forth between the two languages. Guttman,Perkins Expires 6 December 1997 [Page 2] Internet Draft Service Templates and URLs 6 June 1997 A Service may use templates to register services in more than one language, though it has been configured by the system administrator to register in a single language. QUESTION: Which of several homonyms would be the one known to user agents processing the translated information? All grammar encoding follows the Augmented BNF (ABNF) [6] for syntax specifications with a few deviations. QUESTION: What are the deviations? 1.1. Terminology In order to reduce confusion, some terminology is introduced. service: URL A URL, registered by a service agent of a particular service type, that conforms to any "service scheme" definition. service type A type of service all of whose agents are accessed by service: URLs of the same scheme (a service scheme, below). The name of the type of service is the part of the service scheme name which follows the initial string "service:". service scheme A scheme, whose name start with the string "service:" and is followed by the service type name, constructed according to the rules in this document. service template A formal description of the service attributes and service scheme associated with a particular service type. a particular service may be selected by obtaining the service: URL registered by that service. general service template A template for describing service templates -- for instance as is contained within this document. Guttman,Perkins Expires 6 December 1997 [Page 3] Internet Draft Service Templates and URLs 6 June 1997 1.2. Service Schemes Each service scheme MUST obey the URL conventions defined in [4]. The scheme specific information following the service: scheme provides the service type and address of a network service. It may additionally include service type specific information. The form of a service: URL is as follows: "service:" service-type ":" service-part where the service-part typically has the following form: /addr-family/addr-spec/url-path;FAQ and the last field is never required to exist in any service location registration, but is sometimes provided for convenience of interactive user agents. The formal syntax for a service: URL is given in Section 5. The service-type string indicates the type of service. The service type determines the semantics of the service-part and of the attributes associated with the service: URL. The is IP by default (if not present), but can be used to indicate the use other address families such as IPX and Appletalk. In this document, the addr-family> is always IP, so that the field can be omitted; all service-parts will start with "//". Next, the service-part includes a address specification (an ), which is typically either a domain name (DNS) or an IP address for the service, and possibly a port number. The service-part allows more information to be provided (by way of ) that can uniquely locate the service or resource if the is not sufficient for that purpose. The FAQ is actually composed of a list of "attribute = value" elements, describing for the user the attributes that are associated with the service: URL. This might be done in situations where the service: URL is used in a context where it was not automatically selected by picking desired attributes. When a human obtains a URL and needs to ask questions about how to use it, hopefully the attribute values provided in the FAQ can help. For instance, if the keyword "PostScript" were provided in a service:printer URL, a user would be able to guess that the printer could correctly print PostScript documents. Other than in a FAQ, attributes associated with the service: URL are not typically included in the URL. They are stored and retrieved using other mechanisms. The service: URL is uniquely identified with a particular service agent, and is used when registering Guttman,Perkins Expires 6 December 1997 [Page 4] Internet Draft Service Templates and URLs 6 June 1997 or requesting the attribute information. The Service Location Protocol [10] specifies how such information may be advertised by network services and obtained by client software. Service agents would not typically advertise URLs with FAQs unless manually configured to do so by a system administrator, and a user agent that obtains a service: URLs by issuing a Service Request will already have all the necessary attribute information to make use of the service: URL. Attributes are associated with service: URLs for three reasons: 1. Many servers have optional features. Clients which require or prefer to make use of these features can proceed to do so without protocol negotiation or feature selection. Attributes serve as a mechanism for servers to distribute information about their configuration, capabilities and characteristics (even dynamic qualities, such as status or load.) 2. Client software may have particular requirements. The attributes associated with a given URL allow for automatic selection of services which have certain features. For example, client software may require a server which has a particular version of something, or which has access to specific resources. 3. Attributes support selection of service instances by characteristic as opposed to simply by type. These attributes may be used to give users information enabling the selection of particular services when browsing service directories or the available services on the local network. 1.3. Related work The "Finding Stuff" work by Ryan Moats and Martin Hamilton uses service: URLs provide access information about arbitrary network protocols through DNS [9]. They do not associate service attributes with these URLs. The URLs may contain nonstandard service port information for services advertised in the DNS. DNS SRV Resource Records are a mechanism which provides a way to obtain a service by type for a given domain [7], without being able to specify which of the (possibly numerous) instances of the service type would satisfy the needs of the user agent. 1.4. Changes made since the last version Removed: Guttman,Perkins Expires 6 December 1997 [Page 5] Internet Draft Service Templates and URLs 6 June 1997 - The long template examples. - Description of the Service Specific Multicast Addresses (which are no longer needed in the Service Templates.) - 'Record based' attribute values. - The possibility for putting CR, LF, or TAB in most places. Added: - Terminology - Further explanation of Service Templates. - New syntax for Service Templates. - A proposal on how to use Templates for internationalization. - Some security considerations. 1.5. Open issues and work to be done - Justification will be added (as done in the URL process draft [3]). - Encoding rules for transforming a Service Template to an LDAP Schema will be added. - The process for standardizing a new service type needes to be sharpened. In particular, feedback from the Applications Area Directors needs to be solicited. - Description of how Service Templates themselves may be registered and obtained in a network is needed. Why isn't SLP enough for this purpose? 2. Use of service: URLs The service: URL is intended to allow arbitrary client/server and peer to peer systems to make use of a standardized dynamic service access point discovery mechanism. It is intended that service: URLs be selected according to the suitability of associated attributes. A client application may obtain the URLs of several services of the same type and distinguish Guttman,Perkins Expires 6 December 1997 [Page 6] Internet Draft Service Templates and URLs 6 June 1997 the most preferable among them by means of their attributes. The client will use the service: URL to bind directly to a service. These attributes will be specified as shown with the "service- template", described below. If a service: URL is stored by a client or an agent representing a client, the agent SHOULD also keep track of the attributes which characterize the service offered at the network location indicated by the URL, and can use the service template for additional information about those service attributes. The registration of this attribute information is typically done using the Service Location Protocol [10], although manual techniques and other protocols may be possible. 3. Specifying A New Service Type A Service Type defines the syntax for all URLs that will be registered by services of the particular type. For instance, a 'Printer' service type is defined with service: URLs in the following form: service:printer://
/ The service agent registering the printer service can be selected by clients specifying the protocol which matches the protocol attribute registered with the printer URL above. The attribute information can be used to indicate other configuration details, optional features available and characteristics (which may be relevent to a human user or to a program.) 3.1. Service Type Specifications Service Type specifications define the fields described in the following subsections, and define the syntax of the service-part of service: URLs of that service type. 3.1.1. Service Type This is a string which will be prepended by the 'service:' scheme. It may be a name which is entirely invented or be the same as a well known service scheme. For example, service:http: might refer to a HTTP server, whereas the http: scheme used in a URL generally refers to a document. The meaning of this service type must be fully described by service type specification. A network protocol specification is often Guttman,Perkins Expires 6 December 1997 [Page 7] Internet Draft Service Templates and URLs 6 June 1997 included as one of the attributes associated with the service, and may optionally be registered by some service agents as part of the service: URL include in the service registration. 3.1.2. The service: 'url-path' information This information is included in the URL in order to provide uniquely identifying information. This mechanism is used in the examples which follow in order to identify a mountable filesystem (using the 'nfs' service type) and an lpd print queue (as described above). The syntax and interpretation of the url-path must accompany the definition of a new Service Type. See section 3.3.3, describing the mandatory "template.url-path rules" attribute. The url-path may be very simple, or even entirely omitted except possibly a terminating slash. See [4] for examples and general guidance. 3.1.3. Attributes This information provides information about the service's capabilities, characteristics and required client configuration. Each attribute which is defined must have a default value and definition of all values it can take. An attribute may take one or more values. A keyword does not take any values. Registration, deregistration and the use of attributes in queries may be accomplished using Service Location Protocol, or possibly other means beyond the scope of this document. 3.2. Specifying Attributes Attributes are used to convey information about a given service for purposes of differentiating different services of the same type. They convey information to be used in the selection of which service to bind to, either browsers or for use by a program. Attributes may be encoded in different character sets and in different languages. The procedure for doing this is described in Section 9. Attributes definitions have several components. 1. The first is a 'tag'. This is a string with certain encoding rules. Guttman,Perkins Expires 6 December 1997 [Page 8] Internet Draft Service Templates and URLs 6 June 1997 2. Attribute descriptors (type and flags) 3. Possibly, a set of typed values. 4. Descriptive help text explaining necessary information about what the attribute is Attributes (but not keywords) may have one or more values. Values of an attribute are typed, and must have the same type for each value if the attribute is multivalued. The rules for typing and encoding of attribute values is given in the rest of section 3.2. 3.2.1. Service Templates and attributes Service Templates provide rules for attributes. They define: - Which attributes are REQUIRED with every service registration of a given service type, and which are OPTIONAL. - The type of values possible for the attribute (e.g., STRING). - Whether the attribute may take multiple values. - Whether the attribute may take arbitrary values or only those provided in the list. - Whether the attribute may be translated to other languages or is a 'literal', ie. not meant for human readability. - Whether the service: URL can be be supplied in response to a request that does not give a value for the attribute, when the attribute is used as part of the registration for that service: URL. 3.2.2. Service Templates String Encoding Service templates are encoded in a simple form. They may be translated to any language or character set, but the template used for standardization MUST be encoded in ASCII [2] and be in English. Between each attribute definition there is a blank line. The rules for encoding attributes is given below. Reserved characters include ";", "&", "=", ",", "*", "#", TAB, LF, and CR. Reserved characters may be escaped. The escaped character is replaced by a character sequence with no spaces. The digits are a decimal representation of Guttman,Perkins Expires 6 December 1997 [Page 9] Internet Draft Service Templates and URLs 6 June 1997 the character value to be replaced, in the character set used for the attribute encoding. Some attributes may take values only among those present in a specified value list. A keyword has no value list included. Any attribute or keyword definition may include help text which can be used to provide interactive descriptions helpful to people browsing the available services. This descriptive text is often used to explain technical details about the attribute or about the values which the attribute can take. esc-char = "&" "#" 1*DIGIT ";" The following special case should be noted: - Commas are used to separate list elements (e.g., allowable attribute values. To use a comma in attribute encodings, escape the comma with , Service Templates have the following ABNF [6] grammar: NOTE that this grammar is not quite correct yet, because it needs a lot of work on specifying the scheme-def. template = scheme-props scheme-def attr-defs schemeatrs = schemevers schemelang schemetype schemetext schemevers = "Version" "=" 1*DIGIT "." 1*DIGIT schemelang = "Language" "=" 2*2lower-alpha schemetype = "Type" "=" *schemechar schemechar = ALPHA / DIGIT / "-" / "_" / "$" / "+" / "@" / "." / "|" / "<" / ">" / "~" schemetext = "Scheme-description" "=" [help-text] scheme-def = url-path-rules ; Rules for constructing service: URLs: ; The scheme-def part of the template will ; be text describing the allowable format ; of information in the url-path of the ; service-part of the service scheme. ; The and FAQ fields do not ; require additional specification. attr-defs = *(attr-def/keydef) attr-def = tag "=" attrtail newline keydef = keyword "=" "KEYWORD" newline attrtail = type flags newline [value-list] [help-text] value-list = 1#value newline help-text = 1#help-line ; This is a human readable description of Guttman,Perkins Expires 6 December 1997 [Page 10] Internet Draft Service Templates and URLs 6 June 1997 ; this attribute and its values. help-line = *[white-sp] "#" *[ com-chars ] newline tag = 1*attrchar keyword = 1*attrchar attrchar = 1*(schemechar / ":" flags = ["M"] ["L"] ["X"] ["O"] ; M means multiple values are allowed ; L "Literal", values MUST NOT be translated ; X means explicit match required ; O "Optional", the attribute may be omitted value = string / integer / boolean / opaque type = "STRING" / "INTEGER" / "BOOLEAN" | "OPAQUE" / "KEYWORD" ; These strings are not to be translated. string = safe-char *[safe-chars / SPACE] safe-char integer = [-] 1*DIGIT ; The integer MUST fall within the range of ; values a 32 bit integer may take, ie. ; -2147483648 to 2147483647. boolean = "TRUE" / "FALSE" ; These strings are not to be translated. com-chars = safe-char / white-sp / "*" / "," / ";"/ "&" safe-char = attrchar / " " / "!" / '"' / "%" / "'" / "(" / ")" / "+" / "," / "-" / "." / "|" / ":" / "=" / "?" / "[" / "]" / "" / "/" / "" / " " ; All ASCII printable characters are ; included except ",", "&", "*" and "#". white-sp = SPACE / TAB rad64-char = ALPHA / DIGIT / "+" / "-" / white-sp opaque = 1*DIGIT ":" 4*rad64-char ; The digits define the original length of ; the opaque value. The restricted character ; string is the radix-64 encoding of the opaque ; value. See [5], Section 5.2. ; NOTE: White space is ignored in decoding ; radix-64 values. newline = CR / ( CR LF ) Guttman,Perkins Expires 6 December 1997 [Page 11] Internet Draft Service Templates and URLs 6 June 1997 ABNF should have some way of denoting a continuation line! Otherwise, it is ambiguous whether a next line is a continuation or starts with some bizarro nonterminal. Note on the use of white space: A string is considered to be a token in the case of a tag or value. In this case, the string is 'trimmed'. White space interior to a string token is left alone, while white space between the tokens is removed. For example: " some name = some value , another example " would be trimmed to "some name" '=' "some value" and "another example". Notes on string matching: Attribute tags and values may be used by some protocols for directory look-up. In this case, the following rules should be applied for string matching of attribute strings. Decoding character escape and trimming white space MUST be performed before string matching. In addition, string matching SHOULD be case insensitive. 3.2.3. Attributes with multiple values Attributes with multiple values must be defined so that the type of each value is the same. Boolean attributes may not take multiple values. Attributes and values must be given in exactly the same order in translated service templates. This will allow the service templates to be used to translate attributes and values to other languages (using service templates as look up tables.) 3.2.4. Grouping attribute values together in records Some attributes may be related, which is to say, not independent. Each configuration, for instance, might have a limitation and a best use. If these were encoded in separate attributes, the dependency would not be clear: Guttman,Perkins Expires 6 December 1997 [Page 12] Internet Draft Service Templates and URLs 6 June 1997 Configuration = A,B,C Restriction = slow,large,unpredictable,low-priority Best Use = cpu-intensive,batch-jobs,interactive-use Which is slow, A, B or C? Are interactive jobs unpredictable? The suggested convention is to choose one of the attributes ranges to be the attribute base. Here, it will be the configuration. The others attributes are, by conventions, extensions of this record. The following makes all dependencies explicit: Configuration-A.Restriction = slow,low-priority Configuration-A.Best-Use = batch-jobs Configuration-B.Restriction = unpredictable Configuration-B.Best-Use = interactive-use Configuration-C.Restriction = large Configuration-C.Best-Use = cpu-intensive Note that the use of such grouping is conventional, by use of the dot as an character, and does not place any constraint on the parsing mechanisms used by agents storing the visually related attribute values. 3.3. Special attributes Every service template must define the following attributes: 3.3.1. Service Type Language This is a two letter code defining the language of the template [8]. 3.3.2. Version The version of the Service Type template. A proposal starts at 0.0, and the minor number increments once per revision. The Version attribute has a string value of the form: version = 1*DIGIT '.' 1*DIGIT A standardized template starts at 1.0. Additions of attributes add one to the minor number, where changes of definition or removal of attributes or values adds one to the major number. See Section 4 for more detail on how to use the Version attribute. Guttman,Perkins Expires 6 December 1997 [Page 13] Internet Draft Service Templates and URLs 6 June 1997 3.3.3. url-path rules This is a text attribute which defines the semantics of the url path of the service: URL of the given type. The is of the form: ///;FAQ The description specifies additional information to locate a service when the is not sufficient, and is a field whose content that distinguishes URLs of a particular service type from those of another service type. For instance, in the case of a printer service: URL, the url-path will typically be a queue name, but not in the case of a service: URL for any other service type. 4. A Process For Standardizing New Service Types New Service Types can be suggested simply by providing a Service Type template and a short description of the use for the service: URL. This MUST have its 'Version' attribute set to "0.0" initially. The minor version number will increment once with each change until it achieves 1.0. There is no guarantee any version of the service template will be backwards compatible before it reaches 1.0. Once a service template has reached 1.0, the definition is "frozen" for that version. New templates may be defined, of course, to refine that definition, but they must follow these rules: - Any new attribute defined for the template will increase the minor version number by one. All other attributes for the version must continue to be supported as before. A client which supports 1.x can still use later versions of 1.y (where x