HTTP/1.1 200 OK Date: Tue, 09 Apr 2002 08:46:05 GMT Server: Apache/1.3.20 (Unix) Last-Modified: Thu, 21 May 1998 01:33:00 GMT ETag: "323cde-7b89-3563844c" Accept-Ranges: bytes Content-Length: 31625 Connection: close Content-Type: text/plain TN3270E Working Group Jim Naugle Internet Draft: Kashturi Kasthurangan IBM Expiration Date: November 98 Gregg Ledford Zephyr Development May 98 TN3270E Service Location and Session Balancing draft-ietf-tn3270e-service-loc-00.txt Status of This Memo 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. Internet Drafts may be updated, replaced, or obsoleted by other documents at any time. It is not appropriate to use Internet Drafts as reference material or to cite them other than as a "working draft" or "work in progress." Please check the I-D abstract listing contained in each Internet Draft directory to learn the current status of this or any Internet Draft. Distribution of this document is unlimited. Copyright Notice Copyright (C) The Internet Society (1998). All Rights Reserved. Abstract This document discusses the implementation of Service Location Protocol and session balancing with a TN3270E emulator in a client server implementation with a TN3270E server. Application program developer's can locate TN3270E services and load balance among those services (3270 host sessions), by using this Service Location Protocol support. Naugle, Kasthurirangan, Ledford Expires November 1998 [Page 1] Internet Draft TN3270E Service Location/Session Balancing May 1998 1. Table of Contents Status of This Memo Abstract 1. Table of Contents 2. Introduction 3. Overview of RFC 2165 3.1 SLP Agents 3.2 SLP Relationships 3.3 User Agents 3.4 SLP Relationships 4. TN3270E Server Environment and Load 4.1 TN3270E Server Load 5. TN3270E Client Configuration 5.1 SLP Scope 5.2 Directory Agent Discovery Time-out 5.3 Service Agent Multicast Time-out 6. Service Registration and Service Templates 7. TN3270E Client Implementation 7.1 Overview 7.2 How to Obtain List of TN3270E Servers Supporting SLP 7.3 TN3270E Sample Client Flow 7.3.1 Open the SLP connection 7.3.2 Query the list of TN3270E servers 7.3.3 Determine loading of each TN3270E server 7.3.4 Closing the SLP connection 7.3.5 Freeing memory structures 7.4 Recommendations 8. Sample Trace Flow of SLP and Session Balancing 9. Service Registration and Service Templates 10. References 11. Author's Addresses Naugle, Kasthurirangan, Ledford Expires November 1998 [Page 2] Internet Draft TN3270E Service Location/Session Balancing May 1998 2. Introduction This document will provide information on Service Location Protocol implementation to discover TN3270E servers in a network and session balance among those servers. The implementation follows the standards track RFC 2165, Service Location Protocol [1]. 3. An overview of RFC 2165 RFC 2165, Service Location Protocol (SLP) [1], provides an automatic way for clients to discover services within an administrative domain. These services have various attributes associated with them from which a client can base a service selection on. The basic design involves the use of three agent types. These are: User Agents (UA's), Service Agents (SA's) and Directory Agents (DA's). 3.1 SLP Agents User Agents are used to query Service Agents or Directory Agents. They acquire/request service information based upon the desired attributes and service needed for the user application. Service Agents represent a specific service and advertise service information. Directory Agents act as a central collection point for service registration information by Service Agents which is later requested by "user agents" in "intranets". 3.2 Service Agents The Service Agent is defined as a process working on behalf of one or more services to advertise service information. Service information is a collection of attributes and configuration information associated with a single service. The Service Agents advertise service information for either one or a collection of service instances. The service itself is a process or system providing a facility to the network, which in our case would be the TN3270 server. The service registers itself with the service agent so that the SA can start advertising this information over the network. The process of registrations consists of the service giving the SA all relevant configuration information and attributes. The format of this information is called the Service template. The service template for TN3270 which is given below contains the URL which is the address of Naugle, Kasthurirangan, Ledford Expires November 1998 [Page 3] Internet Draft TN3270E Service Location/Session Balancing May 1998 the server with the port, which should be used to connect to it. The URL also contains the service type which in this case is TN3270. The template also contains all the other attributes of the service like scope, load etc. 3.3 User Agents The User Agent working on the TN3270 client's behalf retrieves service information from the Service Agent or a Directory Agent and based on the required attributes decides to connect or not with a particular server. Based on the service advertisements from various TN3270 servers, the client looks at the load attribute and can decide to connect to the least loaded server. If by the time it connects to that particular TN3270 server the server becomes unavailable it can try connecting to the next server in its list (ie: the second least loaded server whose advertisement was retrieved by the client/user agent). 3.4 SLP Relationships The diagram below taken from RFC 2165 [1] helps illustrate the agent relationships described above. +---------------+ we want this info: +-----------+ | Application | - - - - - - - - - - - -> | Service | +---------------+ +-----------+ /|\ | | | +-------------+ | | | | \|/ \|/ \|/ +---------------+ +-----------+ +----------------+ | User Agent |<-------->| Service | | Service | +---------------+ | Agent | | Agent which | | +-----------+ | does not reply | | | | to UA requests | | \|/ +----------------+ | +-------------+ | +------------------>| Directory |<----------+ | Agent | +-------------+ ___________ /|\ / Many other\ +------------>| SA's | \___________/ 4. TN3270E Server Environment and Load TN3270E Servers are pervasive in today's networked environment. SLP provides emulator clients with a way to discover TN3270E servers in the network and session balance among the servers. The TN3270E servers could be distributed across different SNA gateways with Naugle, Kasthurirangan, Ledford Expires November 1998 [Page 4] Internet Draft TN3270E Service Location/Session Balancing May 1998 different connection methods to hosts. The use of LU pools provides a easy way for administrators to provide users access to hosts. Administrators can add users to LU pools that have pre-configured LU's with specific attributes, like LU types and model types. These LU pools would typically have LUs from several different gateways assigned, and as members of the LU pool make TN3270E session connections, they would be making connections to different TN3270E servers, with different load factors, so that session balancing could be accomplished. The use of LU pools is not a requirement for SLP and session balancing. A TN3270E client could obtain a session by using SLP and session balancing to locate the least loaded server in the network. On a service request a wild card "*" could be used when asking for LUPOOL if the emulator doesn't care which device types are supported in given pools or if it can assume given pools support only certain device types. (LUPOOL=xyz\t*) 4.1 TN3270E Server Load TN3270E servers providing load information, typically will include number of sessions available, not in current use, as part of the calculation in determining load for that server. There can be other factors that might have an effect on server load. For example, if a server is not dedicated to only SNA traffic, and is handling other processes, like file services and print services, etc. It is beyond the scope of this document to discuss how individual server load calculations should be determined. If the TN3270E server coexists in a network with other TN server implementations using SLP for load balancing, TN3270E server load could be adjusted to compensate for differences in load calculations. One way to allow TN3270E server administrators to compensate for differences in implementations of calculating server load measurement is to provide the ability to modify the load calculation on the TN3270E server. An element of control can be provided by allowing the administrator to modify the load measurement, by using an integral number between 0 and 100 (100 being the highest) to change the load. This load measurement acts as an additional factor on the server's actual load calculation, so that the administrator could bias up or down, the likelihood of that server being selected by a TN3270E client. Load is defined as one of the attributes for the TN3270E server. If a UA provides only a Service Type, in an Attribute Request, then the reply includes all attributes and all values for that Service Naugle, Kasthurirangan, Ledford Expires November 1998 [Page 5] Internet Draft TN3270E Service Location/Session Balancing May 1998 Type, and Load would be included. Attribute Requests can include a select clause, so you could just be returned information on load for each server. For more information on Attribute Requests refer to Service Location Protocol Internet draft [4]. An application could issue a SL_GetService request to locate a TN3270E server. Then an application designed to perform least-load location of a TN3270E service, could issue a series of SL_GetAttrs calls directed to each URL to obtain the load measurement of each server. It would specify a select clause similar to the one below to receive only load information. URL = service:tn3270://9.37.51.254:23 Attribute filter = LOAD The attribute LOAD would be returned along with its value. The application could then issue other SL_GetAttrs calls to each URL. The application would then select the least loaded server as a connection target. If it tries to connect to a server and that connection fails, it could then try to connect to the next least-loaded server. 5. TN3270E Client Configuration 5.1 SLP Scope Scope is a parameter used to control and manage access by clients to servers in a network. It is the same as the Service Location Protocol scope defined in RFC 2165 [1]. The control scope provides is necessary for two reasons: As your network, the number of clients, and the number of servers grow, it becomes necessary to partition access to those servers by the growing number of clients in order to reduce overall traffic on the network. It allows administrators to organize users and servers in to administrative groups. The meaning of the values of scope is defined by the administrator of the network. These values can represent any entity. Commonly, they fall along either departmental, geographical, or organizational lines. Each TN3270E server can be assigned to a scope or scopes. TN3270E clients using these servers can be configured for a single specific scope or be unscoped. Different scopes can be assigned for different services provided on the server if desired. Naugle, Kasthurirangan, Ledford Expires November 1998 [Page 6] Internet Draft TN3270E Service Location/Session Balancing May 1998 SLP Service Agents and Directory Agents need to reside in the network that support the TN3270E server with configured scopes. If you plan to allow clients to locate TN3270E server services based on scopes, keep in mind how scope relates to the network as a whole. If there are unscoped services in a network where scopes are also used, then these services are eligible to satisfy any scoped requests, which can potentially put a burden on those service agents and directory agents that support the unscoped services. For this reason, we recommend that every reachable server either have a scope, or no server has a scope defined. If directory agents are to be used in the site network (for upward scaling), then they should be configured to handle the same scopes as is set for the TN3270E servers. In addition, if unscoped services are to be used in networks with directory agents, at least one unscoped directory agent should be set up. Discovery - the scope value can be discovered using the SL_GetAttrs API by issuing an unscoped attribute request for a service type with an attribute filter of "SCOPE". This API returns a list of scopes for services currently active in the network. The list can be displayed for user selection. For more information on SLP scope refer to Service Location Protocol Internet draft [4]. 5.2 DA-Discovery time-out The DA Discovery time-out value, a parameter on the SLP_Open API, is used to control how long the SLP API must wait to discover Directory Agents (DAs) in the network. The discovery request is a multicast, and the amount of time required to gather all DA responses might vary depending on many factors. If there are no DAs in the network, this time-out value can be set to zero to indicate that no DA discovery is to be done. The time-out is expressed in milliseconds. 5.3 SA Multicast time-out The SA Multicast time-out value. a parameter on the SL_Open API, is used to control how long the SLP API must wait to discover services, attributes, or service types in a network without at least one DA that supports the scope of the request. In this situation, these requests are multicast and the SLP API waits the time-out value to gather the multiple responses that are returned. The time-out is expressed in milliseconds. 6. Service Registration and Service Templates The Service Location Protocol uses the ''service:'' URL scheme name Naugle, Kasthurirangan, Ledford Expires November 1998 [Page 7] Internet Draft TN3270E Service Location/Session Balancing May 1998 to define URLs called ''service: URLs''. These schemes provide a way for clients to obtain configuration information that is needed to establish a 3270 session through the Telnet server. The Service Location Protocol provides for service: URLs to be registered and discovered. Service Registration These service registrations contain a service: URL, and possible attributes associated with that service. The service registration templates are shown in section 9 below for the communications server and the TN3270E server. Service Templates Service templates are documents defining in a formal way the attributes associated with that service that a client may want to use. For more information on service templates please refer to, Service Templates and service: Schemes. [3]. The service templates are shown in section 9 for the communications server service and the TN3270E service. 7. TN3270E Client Implementation Information 7.1 Overview A TN3270E client that implements TN3270E SLP load balancing does not need to configure an IP Host Address for the TN3270E server it desires to connect to. Instead, the IP Host Address of the least loaded TN3270E server is discovered by using the SLP load balancing described in this document. The discovery of the least loaded TN3270E server is done entirely outside of and before the TN3270E telnet negotiation. Once the IP Host address of the least loaded TN3270E server is discovered, the TN3270E client can then start normal TN3270E telnet negotiation. The TN3270E client should allow for configuration of the following parameters: Enable SLP Load Balancing This configuration parameter indicates whether or not SLP load balancing is enabled. If it is enabled the following three configuration parameters must also be configured. If this parameter is disabled, SLP load balancing is not supported and normal TN3270E telnet negotiation is performed. Scope Name The scope name is a text string that specifies a group of TN3270E Naugle, Kasthurirangan, Ledford Expires November 1998 [Page 8] Internet Draft TN3270E Service Location/Session Balancing May 1998 servers. The scope name can be used to identify groups of TN3270E servers in a departmental or geographic setting. For example, if the scope name is Building-D, then the SLP load balancing would search all TN3270E servers in the Building-D scope to find the least loaded TN3270E server. If the scope name is blank, then the scope name is not used. This is referred to as unscoped. All TN3270E servers, with or without scope names, can be used to satisfy the request for least loaded TN3270E servers. Because of the amount of network overhead that this involves, this is not recommended. DA Discovery Time Out Value This value is specified in milliseconds and is fully described in section 5.2 of this document. SA Multicast Time Out Value This value is specified in milliseconds and is fully described in section 5.3 of this document. 7.2 How to obtain the list of TN3270E servers supporting SLP A TN3270E client that implements SLP load balancing uses API calls to obtain the list of TN3270E servers supporting SLP load balancing. These API calls are described in "An API for Service Location" [2]. The following API calls are a subset of those described in "An API for Service Location" [2] and can be used with TN3270E SLP session balancing. SL_Open SL_GetService SL_GetAttrs SL_FreeResult SL_Close 7.3 TN3270E Sample Client Flow 7.3.1 Open the SLP connection The TN3270E client must first open the SLP library using the SL_Open API call. The SA multicast time out and DA discovery time out values are passed as parameters to the SL_OPEN API call. 7.3.2 Query the list of TN3270E servers The TN3270E client then queries for the list of TN3270E servers Naugle, Kasthurirangan, Ledford Expires November 1998 [Page 9] Internet Draft TN3270E Service Location/Session Balancing May 1998 supporting SLP. This is done by using the SL_GetService API call. The request string contains information that determines which type of TN3270E servers that this client desires to connect to. The request string can contain the scope name, pool name, session type and 3270 screen size. The string has the following format: TN3270//LUPOOL == The is the name of the scope that is configured for the TN3270E client. If the scope is blank or null (unscoped request), then the scope is not inserted into the request string. The is a 1 to 8 character upper case string that indicates the name of the pool that the TN3270E client desires to connect to. For SLP load balancing, the same pool name must be configured on different TN3270E servers. The is the '/t' tab character which is hexadecimal 0x09. The can be any of the following: 3270DSC for TN3270E device type IBM-3287-1 3270002 for TN3270E device types IBM-3278-2 and IBM-3278-2-E 3270003 for TN3270E device types IBM-3278-3 and IBM-3278-3-E 3270004 for TN3270E device types IBM-3278-4 and IBM-3278-4-E 3270005 for TN3270E device types IBM-3278-5 and IBM-3278-5-E * for TN3270E device type IBM-DYNAMIC Example: For a TN3270E client searching for TN3270E servers in the ENGINEERING scope for a model 2 screen size and LUPOOL name pool2, the following request string would be constructed: "TN3270/ENGINEERING/LUPOOL == pool23270002" Note: The " characters before and after the string are not part of the request string. 7.3.3 Determine loading of each TN3270E server Once the list of TN3270E servers and their respective IP Host addresses is constructed, each of the TN3270E servers must be interrogated to find the loading of each TN3270E server. Then the TN3270E client can determine which TN3270E server is least loaded, Naugle, Kasthurirangan, Ledford Expires November 1998 [Page 10] Internet Draft TN3270E Service Location/Session Balancing May 1998 and use that IP Host address to connect to. The TN3270E client uses these load values to determine which TN3270E server is least loaded. The TN3270E client then uses the TN3270E server's IP Host address to start normal Telnet TN3270E negotiation. 7.4 Recommendations It is recommended that the TN3270E client display the IP host address that is being used for the TN3270E connection. This gives the user knowledge of which TN3270E server the session is connected to. For example, the IP host address could be displayed in the Windows status bar. It is also recommended that the TN3270E client display the resource name that is returned by the TN3270E server after connection and TN3270E negotiation is completed. This gives the user knowledge of which LU resource name in the LUPOOL the session is connected to. For example, the resource name could be displayed in the Windows status bar, or even in the 3270 OIA line. In the event that after the TN3270E client has determined the least loaded server and the connection to that server fails for some reason, the connection should be closed and an attempt made to connect to other TN3270E servers in the list of least loaded servers. For example, a TN3270E server may reject a connection to a specific pool if the pool is full, or if the device type does not match what is available in the pool. If this occurs, then an attempt to other least loaded TN3270E servers should be performed. 8. Sample Trace Flow of SLP and Session Balancing This sample trace flow is provided for informational purposes only. SLP: SL_GetService Request: TN3270//LUPOOL == POOL2 3270002/ SLP: service:tn3270://206.109.45.139:1366, LOAD = 8 SLP: service:tn3270://206.109.45.140:1366, LOAD = 26 Connecting to 206.109.45.139... TerminalType=NVT Connection established Naugle, Kasthurirangan, Ledford Expires November 1998 [Page 11] Internet Draft TN3270E Service Location/Session Balancing May 1998 Recv <- DO TN3270E Send -> WILL TN3270E TerminalType=TN3270E Recv <- SEND DEVICE_TYPE Send -> DEVICE_TYPE REQUEST IBM-3278-2-E CONNECT POOL2 Recv <- DEVICE_TYPE IS IBM-3278-2-E CONNECT TN8003 Send -> FUNCTIONS REQUEST BIND_IMAGE SYSREQ Recv <- FUNCTIONS IS BIND_IMAGE SYSREQ 9. Service Registration Messages and Service Templates See TN3270E Service Location and Session Balancing Templates Internet Draft for submitted templates to IANA for registration. [5] Communications Server Service Template URL:service:commserver://: The communications server service type is registered whenever the communications software is loaded on the server. It describes generic attributes of the communications server. These attributes are also repeated on the other service types provided. Release = This is the version and release level of the commserver advertising services. Its format is vv.rr.mm where "vv" is the major version number, "rr" is the minor version number, and "mm" is the modification level. All numbers are padded on the left with zeroes to two characters. Example: version 3, release 0, mod level 0 is "03.00.00" Platform = This is the network operating system platform underlying the advertising service. The defined values are: IW Server uses the IntranetWare network operating system NT Server uses the Microsoft NT operating system Naugle, Kasthurirangan, Ledford Expires November 1998 [Page 12] Internet Draft TN3270E Service Location/Session Balancing May 1998 OS2 Server uses the OS2 operating system AIX Server uses the AIX operating system Protocol = This is the protocol(s) supported by the server providing this service. The defined values are: IP Server supports client connections over IP (TCP/IP or UDP/IP) IPX Server supports client connections over IPX (SPX/IPX) Server name = This is the name of the server that was configured during installation. This value has meaning only for the IW platform. Communications Server Service Registration Message URL:service:commserver://: Attributes: [(SCOPE=),] (RELEASE=03.00.00), (PLATFORM=IW), (PROTOCOL=IP), (SERVERNAME=) TN3270 Service Template URL: service:tn3270://: The tn3270 service provides 3270 gateway access to an SNA network via the TN3270 protocol. The attributes reflect the types of 3270 devices, LU Pools, and load information available on the server. Load = : This is the load balancing quantity to use in determining the least loaded comm server to attach to for the service. The range of valid values is an integral 0 to 100 with 0 indicating the lowest Naugle, Kasthurirangan, Ledford Expires November 1998 [Page 13] Internet Draft TN3270E Service Location/Session Balancing May 1998 possible load and 100 the highest. LU Pool = , /t , /t, ... /t Identifies the LU pool names of LU pools available for use on this service with the associated device types supported in each pool. Each value is a record where the first token is the pool name of the pool and the second token is a device type supported in that pool. A pool name without a device type indicates that LUs of unknown type are included in the pool. Records associated with a given pool name are repeated for each supported device type. A given pool is included in a registration request if any PU profile that contributes at least one LU to the pool is active on the server. The range of valid dev_types are: dev_type Meaning 3270002 Lu Type 2 Model 2 3270003 Lu Type 2 Model 3 3270004 Lu Type 2 Model 4 3270005 Lu Type 2 Model 5 3270DSC Printer LU BIND, DATA, RESPONSES, SCS, SYSREQ These keyword attributes describe the TN3270e functions supported by this service. BIND The server supports the SNA bind image function DATA The non-SNA 3270 data stream is supported by server RESPONSES The server supports SNA response mode SCS The server supports SNA 3270 SCS data stream SYSREQ The SYSREQ keyboard key is supported on server Naugle, Kasthurirangan, Ledford Expires November 1998 [Page 14] Internet Draft TN3270E Service Location/Session Balancing May 1998 They are present in the service advertisement if the functions they describe are available. Security = This field will contain the security technique supported by the server. The actual values are currently being defined in the Internet standards body. RFC1576, RFC1646, RFC1647 The RFC numbers that document features supported by the service. Current RFC's for TN3270 include 1576, 1646, and 1647. TN3270 Service Registration Message URL: service:tn3270://: Attributes: [(SCOPE=),] (RELEASE=03.00.00), (PLATFORM=IW), (PROTOCOL=IP), (SERVERNAME=), (LOAD=), [(LUPOOL=pool-name0/tANY, pool-name1/tdevice_type1, pool-name2/tdevice-type2, ... pool-namen/tdevice-typen)] BIND, DATA, RESPONSES, SCS, SYSREQ, Naugle, Kasthurirangan, Ledford Expires November 1998 [Page 15] Internet Draft TN3270E Service Location/Session Balancing May 1998 (SECURITY=NONE), RFC1576, RFC1646, RFC1647, 10. References Request For Comments (RFC) and Internet Draft documents are available from and numerous mirror sites. [1] J. Veizades, E. Guttman, C. Perkins, and S. Kaplan. Service Location Protocol. RFC 2165, July 1997. [2] J. Kempf, E. Guttman, Don Provan. An API for Service Location. (work in progress), March 1998. [3] E. Guttman, C. Perkins, J. Kempf. Service Templates and service: Schemes. draft-ietf-svrloc-service-scheme-07.txt February 98 (work in progress) [4] E. Guttman, C. Perkins, J. Veizades, Michael Day. Service Location Protocol, draft-ietf-svrloc-protocol-v2-01.txt October 1997 (work in progress) [5] J. Naugle, K. Kasthurirangan. TN3270E Service Location and Session Balancing Templates. May 1997 Individual Contribution 11. Authors' addresses Jim Naugle IBM P.O. Box 12195 Research Triangle Park, N.C. 27709-2195 USA Phone: (919) 254-8789 EMail: jnaugle@us.ibm.com Kathuri Kasthurirangan IBM P.O. Box 12195 Research Triangle Park, N.C. 27709-2195 USA Phone: (919) 254-5721 Naugle, Kasthurirangan, Ledford Expires November 1998 [Page 16] Internet Draft TN3270E Service Location/Session Balancing May 1998 Gregg Ledford Zephyr Development Corporation 8 Greenway Plaza Suite 1400 Houston, Texas 77046 USA Phone: (713) 623-0089 Email: gledford@zephyrcorp.com Naugle, Kasthurirangan, Ledford Expires November 1998 [Page 17]