Network Working Group Paul J. Leach, Microsoft INTERNET-DRAFT Dilip C. Naik, Microsoft draft-leach-cifs-browser-spec-00.txt Category: Informational Expires June 10, 1997 January 10, 1997 CIFS/E Browser Protocol Preliminary Draft STATUS OF THIS MEMO THIS IS A PRELIMINARY DRAFT OF AN INTERNET-DRAFT. IT DOES NOT REPRESENT THE CONSENSUS OF ANY WORKING GROUP. 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 (Europe), munnari.oz.au (Pacific Rim), ds.internic.net (US East Coast), or ftp.isi.edu (US West Coast). Distribution of this document is unlimited. Please send comments to the authors or the CIFS mailing list at . Discussions of the mailing list are archived at . ABSTRACT The CIFS/E (CIFS extensions for enterprise networks) family of protocols includes a protocol for browsing. Browsing is a mechanism for discovering servers that are running particular services (not just CIFS file services). Servers are organized into named groups called domains, which form browsing scopes. This document specifies version 1.15 of the browsing protocol. It also specifies the mailslot protocol, because the browsing protocol depends on it (and is the only CIFS/E protocol which does). Leach, Naik [Page 1] INTERNET-DRAFT CIFS/E Browser Protocol January 10, 1997 Table of Contents 1. INTRODUCTION........................................................3 2. PREREQUISITES.......................................................3 3. BROWSER OVERVIEW....................................................3 4. BROWSING PROTOCOL ARCHITECTURE......................................5 4.1 LAYERING OF BROWSING PROTOCOL REQUESTS ...........................5 4.2 BROWSER CLIENT ...................................................7 4.3 NON-BROWSER SERVER ...............................................8 4.4 BROWSER SERVERS ..................................................9 4.4.1 Potential Browser Server ......................................9 4.4.2 Backup Browser ................................................9 4.4.3 Master Browser ...............................................10 4.4.4 Domain Master Browser ........................................13 5. MAILSLOT PROTOCOL SPECIFICATION....................................13 6. BROWSER PROTOCOL SPECIFICATION.....................................15 6.1 NETBIOS NAME NOTATION ...........................................15 6.2 GETB L ACKUP ISTREQUEST BROWSER FRAME ..............................16 6.3 GETBACKUPLISTRESPONSE BROWSER FRAME .............................16 6.4 THE NETSERVERENUM2 RAP SERVICE ..................................17 6.4.1 Transaction Request Parameters section .......................18 6.4.2 Transaction Request Data section .............................19 Leach, Naik [Page 2] INTERNET-DRAFT CIFS/E Browser Protocol January 10, 1997 6.4.3 Transaction Response Parameters section ......................19 6.4.4 Transaction Response Data section ............................20 6.5 HOSTANNOUNCEMENT BROWSER FRAME ..................................21 6.6 ANNOUNCEMENTREQUEST BROWSER FRAME ...............................22 6.7 REQUESTELECTION BROWSER FRAME ...................................23 6.8 BROWSER ELECTIONS ...............................................24 6.9 BECOMEBACKUP BROWSER FRAME ......................................25 6.10 LOCALMASTERANNOUNCEMENT BROWSER FRAME ..........................25 6.11 MASTERANNOUNCEMENT BROWSER FRAME ...............................27 6.12 DOMAINANNOUNCEMENT BROWSER FRAME ...............................27 7. REFERENCES.........................................................28 8. AUTHOR'S ADDRESSES.................................................28 9. APPENDIX A - MULTI-NET CONSIDERATIONS..............................29 10. APPENDIX B - PRIMARY DOMAIN CONTROLLER LOCATION PROTOCOL..........29 11. APPENDIX C - SUMMARY OF SPECIAL NETBIOS NAMES.....................31 11.1 REGISTERED UNIQUE NAMES ........................................31 11.2 REGISTERED GROUP NAMES .........................................32 12. APPENDIX D - BROWSING PROTOCOL EVOLUTION..........................32 1. Introduction The CIFS/E (CIFS extensions for enterprise networks) family of protocols includes a protocol for "browsing". Browsing is a mechanism for Leach, Naik [Page 3] INTERNET-DRAFT CIFS/E Browser Protocol January 10, 1997 discovering servers that are running particular services (not just CIFS file services). Servers are organized into named groups called "domains", which form browsing scopes. This document specifies version 1.15 of the browsing protocol. It also specifies the mailslot protocol, because the browsing protocol depends on it (and is the only CIFS/E protocol which does). This document uses the traditional RFC keywords MUST, SHOULD, etc., (now documented in [Bradner 96]) to indicate requirement levels for interoperability. Note: This document is about CIFS/E browsers and has nothing to do whatsoever with Web browsers such as Internet Explorer and Netscape Navigator. This is a specification for persons interested in implementing a browser server or client that can inter-operate with other CIFS/E browsers and clients. 2. Prerequisites . Familiarity with Common Internet File System specification (CIFS) in general and the Transact2 SMB as well as Remote Administration Protocol in particular [CIFS 96] . Familiarity with concepts of subnets and NETBIOS [RFC 1001]. Additional information about browsing may be found in the MSDN articles _Browsing and Windows 95_ Parts I, II and III. These articles cover considerations for browser deployment, especially in a WAN environment. 3. Browser Overview Hosts involved in the browsing process can be separated into two distinct groups, browser clients and browser servers (often referred to simply as _browsers_). A browser is a server which maintains information about servers _ primarily the domain they are in and the services that they are running -- and about domains. Browsers may assume several different roles in their lifetimes, and dynamically switch between them. Browser clients are of two types: workstations and (non-browser) servers. In the context of browsing, workstations query browsers for the information they contain; servers supply browsers the information by registering with them. Note that, at times, browsers may themselves behave as browser clients and query other browsers. For the purposes of this specification, a domain is simply a name with which to associate a group of resources such as computers, servers and users. Domains allow a convenient means for browser clients to restrict the scope of a search when they query browser servers. Every domain has a _master_ server called the Primary Domain Controller (PDC) that manages various activities within the domain. One browser for each domain on a subnet is designated the Local Master Browser for that domain. Servers in its domain on the subnet register Leach, Naik [Page 4] INTERNET-DRAFT CIFS/E Browser Protocol January 10, 1997 with it, as do the Local Master Browsers for other domains on the subnet. It uses these registrations to maintain authoritative information about its domain on its subnet. If there are other subnets in the network, it also knows the name of the server running the domain's Domain Master Browser; it registers with it, and uses it to obtain information about the rest of the network (see below). Clients on a subnet query browsers designated as the Backup Browsers for the subnet (not the Master Browser). Backup Browsers maintain a copy of the information on the Local Master Browser; they get it by periodically querying the Local Master Browser for all of its information. Clients find the Backup Browsers by asking the Local Master Browser. Clients are expected to spread their queries evenly across Backup Browsers to balance the load. The Local Master Browser is dynamically elected automatically. Multiple Backup Browser Servers may exist per subnet; they are selected from among the potential browser servers by the Local Master Browser, which is configured to select enough to handle the expected query load. When the re are multiple subnets, a Domain Master Browser is assigned the task of keeping the multiple subnets in synchronization. The Primary Domain Controller (PDC) always acts as the Domain Master Browser. The Domain Master Browser periodically acts as a client and queries all the Local Master Browsers for its domain, asking them for a list containing all the domains and all the servers in their domain known within their subnets; it merges all the replies into a single master list. This allows a Domain Master Browser server to act as a collection point for inter-subnet browsing information. Local Master Browsers periodically query the Domain Master Browser to retrieve the network-wide information it maintains. When a domain spans only a single subnet, there will not be any distinct Local Master Browser; this role will be handled by the Domain Master Browser. Similarly, the Domain Master Browser is always the Local Master Browser for the subnet it is on. When a browser client suspects that the Local Master Browser has failed, the client will instigate an election in which the browser servers participate, and some browser servers may change roles. Some characteristics of a good browsing mechanism include: . minimal network traffic . minimum server discovery time . minimum change discovery latency . immunity to machine failures Historically, Browser implementations had been very closely tied to NETBIOS and datagrams. The early implementations caused a lot of broadcast traffic. See Appendix D for an overview that presents how the Browser specification evolved. Leach, Naik [Page 5] INTERNET-DRAFT CIFS/E Browser Protocol January 10, 1997 4. Browsing Protocol Architecture This section first describes the how the browsing protocol is layered, then describes the roles of clients, servers, and browsers in the browsing subsystem. 4.1 Layering of Browsing Protocol Requests Most of the browser functionality is implemented using mailslots. Mailslots provide a mechanism for fast, unreliable unidirectional data transfer; they are named via ASCII _mailslot (path) name_. Mailslots are implemented using the CIFS Transact SMB which is encapsulated in a NETBIOS datagram. Browser protocol requests are sent to browser specific mailslots using some browser-specific NETBIOS names. These datagrams can either be unicast or broadcast, depending on whether the NETBIOS name is a _unique name_ or a _group name_. Various data structures, which are detailed subsequently within this document, flow as the data portion of the Transact SMB. Here is an example of a generic browser SMB, showing how a browser request is encapsulated in a TRANSACT SMB request. Note that the PID, TID, MID, UID, and Flags are all 0 in mailslot requests. Leach, Naik [Page 6] INTERNET-DRAFT CIFS/E Browser Protocol January 10, 1997 SMB: C transact, File = \MAILSLOT\BROWSE SMB: SMB Status = Error Success SMB: Error class = No Error SMB: Error code = No Error SMB: Header: PID = 0x0000 TID = 0x0000 MID = 0x0000 UID = 0x0000 SMB: Tree ID (TID) = 0 (0x0) SMB: Process ID (PID) = 0 (0x0) SMB: User ID (UID) = 0 (0x0) SMB: Multiplex ID (MID) = 0 (0x0) SMB: Flags Summary = 0 (0x0) SMB: Command = C transact SMB: Word count = 17 SMB: Word parameters SMB: Total parm bytes = 0 SMB: Total data bytes = 33 SMB: Max parm bytes = 0 SMB: Max data bytes = 0 SMB: Max setup words = 0 SMB: Transact Flags Summary = 0 (0x0) SMB: ...............0 = Leave session intact SMB: ..............0. = Response required SMB: Transact timeout = 0 (0x0) SMB: Parameter bytes = 0 (0x0) SMB: Parameter offset = 0 (0x0) SMB: Data bytes = 33 (0x21) SMB: Data offset = 86 (0x56) SMB: Setup word count = 3 SMB: Setup words SMB: Mailslot opcode = Write mailslot SMB: Transaction priority = 1 SMB: Mailslot class = Unreliable (broadcast) SMB: Byte count = 50 SMB: Byte parameters SMB: Path name = \MAILSLOT\BROWSE SMB: Transaction data SMB: Data: Number of data bytes remaining = 33 (0x0021) Note the SMB command is Transact, the opcode within the Transact SMB is Mailslot Write, and the browser data structure is carried as the Transact data. The Transaction data begins with an opcode, that signifies the operation and determines the size and structure of data that follows. This opcode is named as per one of the below: HostAnnouncement 1 AnnouncementRequest 2 RequestElection 8 GetBackupListReq 9 GetBackupListResp 10 BecomeBackup 11 DomainAnnouncment 12 MasterAnnouncement 13 LocalMasterAnnouncement 15 Leach, Naik [Page 7] INTERNET-DRAFT CIFS/E Browser Protocol January 10, 1997 Browser datagrams are often referred to as simply browser frames. The frames are in particular, referred to by the name of the opcode within the Transaction data e.g. a GetBackupListReq browser frame, a RequestElection browser frame, etc. The structures that are sent as the data portion of the Transact SMB are described in section(s) 6.2 through 6.12 in this document. These structures are tightly packed, i.e. there are no intervening pad bytes in the structure, unless they are explicitly described as being there. All quantities are sent in native Intel format and multi-byte values are transmitted least significant byte first. Besides mailslots and Transaction SMBs, the other important piece of the browser architecture is the NetServerEnum2 request. This request that allows an application to interrogate a Browser Server and obtain a complete list of resources (servers, domains, etc) known to that Browser server. Details of the NetServerEnum2 request are presented in section 6.4. Some examples of the NetServerEnum2 request being used are when a Local Master Browser sends a NetServerEnum2 request to the Domain Master Browser and vice versa. Another example is when a browser client sends a NetServerEnum2 request to a Backup Browser server. 4.2 Browser Client A browser client is a system running applications which may wish to query for a list of servers for a particular domain (often its own) or a list of all the domains in the network. (For example, such an application is launched when a user clicks on the Network Neighborhood icon on a Windows machine.) A browser client may send a NetServerEnum2 request (see section 6.4) to any Backup Browser serving that domain to obtain such information. A browser client SHOULD keep a list of a few Backup Browsers for its own domain; it MAY cache lists of Backup Browsers for other domains if it browses them frequently, or it may obtain them upon demand. The objective is to minimize the cost of locating Backup Browsers each time it wants to make a NetServerEnum2 request. A browser client SHOULD distribute its NetServerEnum2 requests randomly among all the Backup Browsers for a domain in its list. The objective is to enable multiple Backup Browsers to effectively handle high browsing loads. A browser client SHOULD NOT send its NetServerEnum2 requests directly to a Master Browser. Browser clients unilaterally sending NetServerEnum2 requests directly to Master Browsers will result in unavoidable congestive collapse in a large enough network. Leach, Naik [Page 8] INTERNET-DRAFT CIFS/E Browser Protocol January 10, 1997 A browser client can locate browser servers for the domain it wants to browse by sending a GetBackupListRequest frame to the Local Master Browser for that domain and waiting for a GetBackupListResponse frame. See section 6.2 and section 6.3, respectively. Once the Local Master Browser server responds with a list of Backup Browser servers, the client should choose several at random from within the response, and cache them. If there is no response after a delay, the GetBackupListRequest frame may be retransmitted. The delay MUST be at least twice the expected service time, and the delay should be doubled after each time-out. In case the Local Master Browser for a domain fails to respond to the GetBackupListRequest, the browser client may attempt to retrieve a list of Backup Browsers by sending a GetBackupListRequest frame directly to the Domain Master Browser for that domain. It can find the Domain Master Browser using the method described in appendix B. A browser client SHOULD force an election by sending a RequestElection frame (see section 6.7) if it does not get a response to a GetBackupListRequest for its own domain after several retransmissions, since it must be assumed that the Local Master browser has crashed. Details of the election process are in sections 6.7 and 6.8. 4.3 Non-Browser Server A non-browser server is a server that has some resource(s) or service(s) it wishes to advertise as being available using the browsing protocol. Examples of non-browser servers would be an SQL server, print server, etc. A non-browser server MUST periodically send a HostAnnouncement browser frame, specifying the type of resources or services it is advertising. Details are in section 6.5. A non-browser server SHOULD announce itself relatively frequently when it first starts up in order to make its presence quickly known to the browsers and thence to potential clients. The frequency of the announcements SHOULD then be gradually stretched, so as to minimize network traffic. Typically, non-browser servers announce themselves once every minute upon start up and then gradually adjust the frequency of the announcements to once every 12 minutes. A non-browser server SHOULD send a HostAnnouncement browser frame specifying a type of 0 just prior to shutting down, to allow it to quickly be removed from the list of available servers. Leach, Naik [Page 9] INTERNET-DRAFT CIFS/E Browser Protocol January 10, 1997 A non-browser server MUST receive and process AnnouncementRequest frames from the Local Master Browser, and MUST respond with a HostAnnouncement frame, after a delay chosen randomly from the interval [0,30] seconds. AnnouncementRequests typically happen when a Local Master Browser starts up with an empty list of servers for the domain, and wants to fill it quickly. The 30 second range for responses prevents the Master Browser from becoming overloaded and losing replies, as well as preventing the network from being flooded with responses. 4.4 Browser Servers The following sections describe the roles of the various types of browser servers. 4.4.1 Potential Browser Server A Potential Browser server is a browser server that is capable of being a Backup Browser server or Master Browser server, but is not currently fulfilling either of those roles. A Potential Browser MUST set type SV_TYPE_POTENTIAL_BROWSER (see section 6.4.1) in its HostAnnouncement until it is ready to shut down. In its last HostAnnouncement frame before it shuts down, it SHOULD specify a type of 0. A Potential Browser server MUST receive and process BecomeBackup frames (see section 6.9) and become a backup browser upon their receipt. A Potential Browser MUST participate in browser elections (see section 6.8). 4.4.2 Backup Browser Backup Browser servers are a subset of the Potential Browsers that have been chosen by the Master Browser on their subnet to be the Backup Browsers for the subnet. A Backup Browser MUST set type SV_TYPE_BACKUP_BROWSER (see section 6.4.1) in its HostAnnouncement until it is ready to shut down. In its last HostAnnouncement frame before it shuts down, it SHOULD specify a type of 0. A Backup Browser MUST listen for a LocalMasterAnnouncement frame (see section 6.10) from the Local Master Browser, and use it to set the name of the Master Browser it queries for the server and domain lists. A Backup Browsers MUST periodically make a NetServerEnum2 request of the Master Browser on its subnet for its domain to get a list of servers Leach, Naik [Page 10] INTERNET-DRAFT CIFS/E Browser Protocol January 10, 1997 in that domain, as well as a list of domains. The period is a configuration option balancing currency of the information with network traffic costs _ a typical value is 15 minutes. A Backup Browser SHOULD force an election by sending a RequestElection frame (see section 6.7) if it does not get a response to its periodic NetServeEnum2 request to the Master Browser. A Backup Browser MUST receive and process NetServerEnum2 requests from browser clients, for its own domain and others. If the request is for a list of servers in its domain, or for a list of domains, it can answer from its internal lists. If the request is for a list of servers in a domain different than the one it serves, it sends a NetServerEnum2 request to the Domain Master Browser for that domain (which it can in find in its list of domains and their Domain Master Browsers). A Backup Browser MUST participate in browser elections (see section 6.8). 4.4.3 Master Browser Master Browsers are responsible for: . indicating it is a Master Browser . receiving server announcements and building a list of such servers and keeping it reasonably up-to-date. . returning lists of Backup Browsers to browser clients. . ensuring an appropriate number of Backup Browsers are available. . announcing their existence to other Master Browsers on their subnet, to the Domain Master Browser for their domain, and to all browsers in their domain on their subnet . forwarding requests for lists of servers on other domains to the Master Browser for that domain . keeping a list of domains in its subnet . synchronizing with the Domain Master Browser (if any) for its domain . participating in browser elections . ensuring that there is only one Master Browser on its subnet A Master Browser MUST set type SV_TYPE_MASTER_BROWSER (see section 6.4.1) in its HostAnnouncement until it is ready to shut down. In its last HostAnnouncement frame before it shuts down, it SHOULD specify a type of 0. A Master Browser MUST receive and process HostAnnouncement frames from servers, adding the server name and other information to its servers list; it must mark them as _authoritative_ entries. Periodically, it MUST check all local server entries to see if a server's HostAnnouncement has timed out (no HostAnnouncement received for three times the periodicity the server gave in the last received HostAnnouncement) and remove timed-out servers from its list. Leach, Naik [Page 11] INTERNET-DRAFT CIFS/E Browser Protocol January 10, 1997 A Master Browser MUST receive and process DomainAnnouncement frames (see section 6.12) and maintain the domain names and their associated (Local) Master Browsers in its internal domain list until they time out; it must mark these as _authoritative_ entries. Periodically, it MUST check all local domain entries to see if a server's DomainAnnouncement has timed out (no DomainAnnouncement received for three times the periodicity the server gave in the last received DomainAnnouncement) and remove timed- out servers from its list. A Master Browser MUST receive and process GetBackupListRequest frames from clients, returning GetBackupListResponse frames containing a list of the Backup Servers for its domain. A Master Browser MUST eventually send BecomeBackup frames (see section 6.9) to one or more Potential Browser servers to increase the number of Backup Browsers if there are not enough Backup Browsers to handle the anticipated query load. Note: possible good times for checking for sufficient backup browsers are after being elected, when timing out server HostAnnouncements, and when receiving a server's HostAnnouncement for the first time. A Master Browser MUST periodically announce itself and the domain it serves to other (Local) Master Browsers on its subnet, by sending a DomainAnnouncement frame (see section 6.12) to its subnet. A Master Browser MUST send a MasterAnnouncement frame (see section 6.11) to the Domain Master Browser after it is first elected, and periodically thereafter. This informs the Domain Master Browser of the presence of all the Master Browsers. A Master Browser MUST periodically announce itself to all browsers for its domain on its subnet by sending a LocalMasterAnnouncement frame (see section 6.10). A Master Browser MUST receive and process NetServerEnum2 requests from browser clients, for its own domain and others. If the request is for a list of servers in its domain, or for a list of domains, it can answer from its internal lists. Entries in its list marked _authoritative_ MUST have the SV_TYPE_LOCAL_LIST_ONLY bit set in the returned results; it must be clear for all other entries. If the request is for a list of servers in a domain different than the one it serves, it sends a NetServerEnum2 request to the Domain Master Browser for that domain (which it can in find in its list of domains and their Domain Master Browsers). Note: The list of servers that the Master Browser maintains and returns to the Backup Browsers, is limited in size to 64K of data. This will limit the number of systems that can be in a browse list in a single workgroup or domain to approximately two thousand systems. Leach, Naik [Page 12] INTERNET-DRAFT CIFS/E Browser Protocol January 10, 1997 A Master Browser SHOULD request all servers to register with it by sending an AnnouncementRequest frame, if, on becoming the Master Browser by winning an election, its server list is empty. Otherwise, clients might get an incomplete list of servers until the servers' periodic registrations fill the server list. If the Master Browser on a subnet is not the Primary Domain Controller (PDC), then it is a Local Master Browser. A Local Master Browser MUST periodically synchronize with the Domain Master Browser (which is the PDC). This synchronization is performed by making a NetServerEnum2 request to the Domain Master Browser and merging the results with its list of servers and domains. An entry from the Domain Master Browser should be marked "non-local", and must not overwrite an entry with the same name marked _authoritative_. The Domain Master Browser is located as specified in Appendix B. A Master Browser MUST participate in browser elections (see section 6.8). A Master Browser for a domain "D" MUST, after winning an election, register the NetBIOS unique name D(1d). A Master Browser for a domain "D" MUST, after losing an election, unregister the NetBIOS unique name D(1d), and do so quickly enough that the winning browser can successfully register it. A Master Browser MUST, if it receives a HostAnnouncement, DomainAnnouncement, or LocalMasterAnnouncement frame another system that claims to be the Master Browser for its domain, demote itself from Master Browser and force an election. This ensures that there is only ever one Master Browser in each workgroup or domain. A Master Browser SHOULD, if it loses an election, become a Backup Browser (without being told to do so by the new Master Browser). Since it has more up-to-date information in its lists than a Potential Browser, it is more efficient to have it be a Backup Browser than to promote a Potential Browser. 4.4.3.1 Preferred Master Browser A Preferred Master Browser supports exactly the same protocol elements as a Potential Browser, except as follows. Leach, Naik [Page 13] INTERNET-DRAFT CIFS/E Browser Protocol January 10, 1997 A Preferred Master Browser MUST always force an election when it starts up. A Preferred Master Browser MUST participate in browser elections (see section 6.8). A Preferred Master Browser MUST set the Preferred Master bit in the RequestElection frame (see section 6.7) to bias the election in its favor. A Preferred Master Browser SHOULD, if it loses an election, automatically become a Backup Browser, without being told to do so by the Master Browser. 4.4.4 Domain Master Browser A Domain Master Browser for a domain MUST act as a Local Master Browser for its subnet. Thus, it acts exactly like a Local Master Browser, except where required to act differently by this section. A Domain Master Browser MUST set type SV_TYPE_DOMAIN_MASTER (see section 6.4.1) in its HostAnnouncement until it is ready to shut down. In its last HostAnnouncement frame before it shuts down, it SHOULD specify a type of 0. A Domain Master Browser for a domain MUST receive and process MasterAnnouncement frames from Local Master Browsers of its domain, and keep a list of all the Local Master Browsers in its domain. A Domain Master Browser MUST periodically synchronize with the Local Master Browsers for its domain. This synchronization is performed by making a NetServerEnum2 request to each Local Master Browser for its "authoritative" entries and merging the results into a master list for the whole domain. Leach, Naik [Page 14] INTERNET-DRAFT CIFS/E Browser Protocol January 10, 1997 A Domain Master Browser MUST eventually purge an entry from its master list if: . it was originally received from a Local Master Browser . it has not appeared in any list obtained from a Local Master Browser for an implementation specific amount of time . it has not received any MasterAnnouncement or HostAnnouncement for the server or domain specified by the entry A Domain Master Browser MUST set the PDC bit in the RequestElection frame (see section 6.7) to bias the election in its favor. A Domain Master Browser MAY be configured with a list of domains for which it is to support cross-domain browsing. It MUST periodically discover or validate the name of the Domain Master Browser for each such domain using the mechanism in appendix B, and add this information to its list of domains and their Domain Master Browsers. 5. Mailslot Protocol Specification The only transaction allowed to a mailslot is a mailslot write. Mailslot writes requests are encapsulated in CIFS TRANSACT SMBs and sent to a specified NetBIOS name. The following table shows the interpretation of the TRANSACT SMB parameters for a mailslot transaction: Name Value Description Command SMB_COM_TRANSACTION Name STRING name of mail slot to write; must start with "\MAILSLOT\" SetupCount 3 Always 3 for mailslot writes Setup[0] 1 Command code == write mailslot Setup[1] Ignored Setup[2] Ignored TotalDataCount n Size of data in bytes to write to the mailslot Leach, Naik [Page 15] INTERNET-DRAFT CIFS/E Browser Protocol January 10, 1997 Data[ n ] The data to write to the mailslot When it is specified that a mailslot message is "sent to NetBIOS name X and mailslot Y" it means that a NetBIOS datagram (as specified in section 4.4.2 of [RFC 1002]) is sent whose . MSG_TYPE is DIRECT_UNIQUE_DATAGRAM if the NetBIOS name is a unique name . MSG_TYPE is DIRECT_GROUP_DATAGRAM if the NetBIOS name is a group name . SOURCE_NAME field is the NetBIOS name of the sending system . DESTINATION_NAME is X . USER_DATA field contains an SMB_COM_TRANSACTION SMB (as specified in the CIFS spec) with its fields as specified in the table above. (or the equivalent, if the NetBIOS service in use is over a protocol other than as specified by RFC 1001/1002.) In order to receive mailslot messages, a system MUST have done a NetBIOS registration (as per section 5.2 of RFC 1001) of the DESTINATION_NAME to which the message was sent. Before sending a mailslot message, the sending system SHOULD have done a NetBIOS registration of the SOURCE_NAME in the message to be sent. 6. Browser Protocol Specification As already explained, browser datagrams are also referred to as Browser frames. What distinguishes one browser frame from another is the opcode that is carried as the data portion of the Transact SMB, and the NETBIOS name and mailslot to which the browser frame is sent. Browser frames are often referred to by the symbolic name of the opcode that is within the data portion of the Transact SMB. The following sections describe the various Browser frames. Leach, Naik [Page 16] INTERNET-DRAFT CIFS/E Browser Protocol January 10, 1997 6.1 NETBIOS Name Notation NAME(xx) denotes the ASCII string "NAME," padded with spaces (0x20) to 15 bytes, with a hex xx value in the 16th byte. For example, the notation FOOBAR(15) indicates a NETBIOS name consisting of the bytes: [69,79,79,65,64,82,20,20,20,20,20,20,20,20,20, 15] Names that are placeholders and that need to be substituted with their actual values are bracketed within <>. Thus the string would become _Redmond_ if the domain under consideration is named _Redmond_. Details of the various NETBIOS names used for browsing are described in Appendix C. 6.2 GetBackupListRequest Browser Frame The GetBackupListRequest frame is sent by a browser client to any Master Browser for a domain to allow the client to learn the identities of Backup Browsers. To get the list of Backup Browsers for domain "D" from the Local Master Browser for that domain, the GetBackupListRequest browser frame is sent to to NETBIOS unique name D(1d) and mailslot _\MAILSLOT\MSBROWSE_. To get the list of Backup Browsers for domain "D" from the Domain Master Browser for that domain, the GetBackupListRequest browser frame is sent to to NETBIOS unique name D(1b) and mailslot _\MAILSLOT\MSBROWSE_. The definition of the GetBackupListRequest frame is: struct { unsigned char OpCode; unsigned short Token; } where : OpCode identifies this structure as a request to return a list of Backup servers. Opcode is defined as GetBackupListRequest and has a value of decimal 9. Token is a handle of meaning only to the client issuing the browser frame. The Local Master Browser will return this token unmodified in the response. The client should use this to distinguish replies to multiple outstanding GetBackupList requests. This implies that every GetBackupListRequest should have an unique handle, at least within the outstanding lifetime of a request. The expected response is a GetBackupListResponse frame (see next section). Leach, Naik [Page 17] INTERNET-DRAFT CIFS/E Browser Protocol January 10, 1997 6.3 GetBackupListResponse Browser Frame The GetBackupListResponse frame is sent by a Master Browser in response to a GetBackupListRequest frame. The GetBackupListResponse frame is sent to the NETBIOS unique name in the SOURCE_NAME of the mailslot message containing the GetBackupListRequest and mailslot \MAILSLOT\LANMAN. Note: this name is not part of the body of the request and on many systems the Master Browser will need to obtain this name from the NetBIOS service. The definition of the GetBackupListResponse frame is: struct { unsigned char OpCode; unsigned short BackupServerCount; unsigned short Token; unsigned char BackupServerList[][] } where: Opcode __Identifies this structure as a backup list. BackupServerCount __Specifies the number of backup servers that follow this list. Token __Is returned unmodified to the client. This is used by the client to associate an incoming BackupListResponse with its BackupListRequest. BackupServerList __ASCII backup servers. Each server name is null terminated and up to 16 bytes in length. 6.4 The NetServerEnum2 RAP Service The NetServerEnum2 RAP service lists all computers of the specified type or types that are visible in the specified domains. It may also enumerate domains. The following definition uses the notation and terminology defined in the CIFS Remote Administration Protocol specification, which is required in order to make it well-defined. The definition is: Leach, Naik [Page 18] INTERNET-DRAFT CIFS/E Browser Protocol January 10, 1997 unsigned short NetServerEnum2 ( unsigned short sLevel, RCVBUF pbBuffer, RCVBUFLEN cbBuffer, ENTCOUNT pcEntriesRead, unsigned short *pcTotalAvail, unsigned long fServerType, char *pszDomain, ); where: sLevel specifies the level of detail (0 or 1) requested. pbBuffer points to the buffer to receive the returned data. If the function is successful, the buffer contains a sequence of server_info_x structures, where x is 0 or 1, depending on the level of detail requested. cbBuffer specifies the size, in bytes, of the buffer pointed to by the pbBuffer parameter. pcEntriesRead points to a 16 bit variable that receives a count of the number of servers enumerated in the buffer. This count is valid only if NetServerEnum2 returns the NERR_Success or ERROR_MORE_DATA values. pcTotal Avail points to a 16 bit variable that receives a count of the total number of available entries. This count is valid only if NetServerEnum2 returns the NERR_Success or ERROR_MORE_DATA values. fServerType specifies the type or types of computers to enumerate. Computers that match at least one of the specified types are returned in the buffer. Possible values are defined in the request parameters section. pszDomain points to a null-terminated string that contains the name of the workgroup in which to enumerate computers of the specified type or types. If the pszDomain parameter is a null string or a null pointer, servers are enumerated for the current domain of the computer. 6.4.1 Transaction Request Parameters section The Transaction request parameters section in this instance contains: . The 16 bit function number for NetServerEnum2 which is 104. . The parameter descriptor string which is "WrLehDz". . The data descriptor string for the (returned) data which is "B16" for level detail 0 or "B16BBDz" for level detail 1. . The actual parameters as described by the parameter descriptor string. The parameters are: Leach, Naik [Page 19] INTERNET-DRAFT CIFS/E Browser Protocol January 10, 1997 . A 16 bit integer with a value of 0 or 1 (corresponding to the "W" in the parameter descriptor string. This represents the level of detail the server is expected to return . A 16 bit integer that contains the size of the receive buffer. . A 32 bit integer that represents the type of servers the function should enumerate. The possible values may be any of the following or a combination of the following: SV_TYPE_WORKSTATION 0x00000001 All workstations SV_TYPE_SERVER 0x00000002 All servers SV_TYPE_SQLSERVER 0x00000004 Any server running with SQL server SV_TYPE_DOMAIN_CTRL 0x00000008 Primary domain controller SV_TYPE_DOMAIN_BAKCTRL 0x00000010 Backup domain controller SV_TYPE_TIME_SOURCE 0x00000020 Server running the timesource service SV_TYPE_AFP 0x00000040 Apple File Protocol servers SV_TYPE_NOVELL 0x00000080 Novell servers SV_TYPE_DOMAIN_MEMBER 0x00000100 Domain Member SV_TYPE_PRINTQ_SERVER 0x00000200 Server sharing print queue SV_TYPE_DIALIN_SERVER 0x00000400 Server running dialin service. SV_TYPE_XENIX_SERVER 0x00000800 Xenix server SV_TYPE_NT 0x00001000 NT server SV_TYPE_WFW 0x00002000 Server running Windows for Workgroups SV_TYPE_SERVER_NT 0x00008000 Windows NT non DC server SV_TYPE_POTENTIAL_BROWSER 0x00010000 Server that can run the browser service SV_TYPE_BACKUP_BROWSER 0x00020000 Backup browser server SV_TYPE_MASTER_BROWSER 0x00040000 Master browser server SV_TYPE_DOMAIN_MASTER 0x00080000 Domain Master Browser server SV_TYPE_LOCAL_LIST_ONLY 0x40000000 Enumerate only entries marked "local"local entries (marked "authoritative"). This is meaningful only for the NetServerEnum2 request and should be ignored within the NetServerEnum2 response. SV_TYPE_DOMAIN_ENUM 0x80000000 Enumerate Domains. The pszDomain parameter must be NULL. . A null terminated ASCII string representing the pszDomain parameter described above Leach, Naik [Page 20] INTERNET-DRAFT CIFS/E Browser Protocol January 10, 1997 6.4.2 Transaction Request Data section There is no data or auxiliary data to send as part of the request. 6.4.3 Transaction Response Parameters section The transaction response parameters section consists of: . A 16 bit word indicating the return status. The possible values are: Code Value Description NERR_Success 0 No errors encountered ERROR_MORE_DATA 234 Additional data is available NERR_ServerNotStarted 2114 The RAP service on the remote computer is not running NERR_BadTransactConfig 2141 The server is not configured for transactions, IPC$ is not shared . A 16 bit "converter" word. . A 16 bit number representing the number of entries returned. . A 16 bit number representing the total number of available entries. If the supplied buffer is large enough, this will equal the number of entries returned. 6.4.4 Transaction Response Data section The return data section consists of a number of SHARE_INFO_1 structures. The number of such structures present is determined by the third entry (described above) in the return parameters section. At level detail 0, the Transaction response data section contains a number of SERVER_INFO_0 data structure. The number of such structures is equal to the 16 bit number returned by the server in the third parameter in the Transaction response parameter section. The SERVER_INFO_0 data structure is defined as: struct SERVER_INFO_0 { char sv0_name[16]; }; where: sv0_name is a null-terminated string that specifies the name of a computer or domain . At level detail 1, the Transaction response data section contains a number of SERVER_INFO_1 data structure. The number of such structures is equal to the 16 bit number returned by the server in the third parameter in the Transaction response parameter section. The SERVER_INFO_1 data structure is defined as: Leach, Naik [Page 21] INTERNET-DRAFT CIFS/E Browser Protocol January 10, 1997 struct SERVER_INFO_1 { char sv1_name[16]; char sv1_version_major; char sv1_version_minor; unsigned long sv1_type; char *sv1_comment_or_master_browser; }; sv1_name contains a null-terminated string that specifies the name of a computer, or a domain name if SV_TYPE_DOMAIN_ENUM is set in sv1_type. sv1_version_major whatever was specified in the HostAnnouncement or DomainAnnouncement frame with which the entry was registered. sv1_version_minor whatever was specified in the HostAnnouncement or DomainAnnouncement frame with which the entry was registered. sv1_type specifies the type of software the computer is running. The member can be one or a combination of the values defined above in the Transaction request parameters section for fServerType. sv1_comment_or_master_browser points to a null-terminated string. If the sv1_type indicates that the entry is for a domain, this specifies the name of server running the domain master browser; otherwise, it specifies a comment describing the server. The comment can be a null string or the pointer may be a null pointer. In case there are multiple SERVER_INFO_1 data structures to return, the server may put all these fixed length structures in the return buffer, leave some space and then put all the variable length data (the actual value of the sv1_comment strings) at the end of the buffer. There is no auxiliary data to receive. 6.5 HostAnnouncement Browser Frame To advertise its presence, i.e. to publish itself as being available, a non-browser server sends a HostAnnouncement browser frame. If the server is a member of domain "D", this frame is sent to the NETBIOS unique name D(1d) and mailslot _\MAILSLOT\MSBROWSE_. The definition of the HostAnnouncement frame is: Leach, Naik [Page 22] INTERNET-DRAFT CIFS/E Browser Protocol January 10, 1997 struct { unsigned char Opcode; unsigned char UpdateCount; unsigned long Periodicity; unsigned char ServerName[]; unsigned char VersionMajor; unsigned char VersionMinor; unsigned long Type; unsigned long Signature; unsigned char Comment[]; } where: Opcode __Identifies this structure as a browser server announcement and is defined as HostAnnouncement with a value of decimal 1. UpdateCount _ must be sent as zero and ignored on receipt. Periodicity __The announcement frequency of the server (in milliseconds). The server will be removed from the browse list if it has not been heard from in 3X its announcement frequency. In no case will the server be removed from the browse list before the period 3X has elapsed. Actual implementations may take more than 3X to actually remove the server from the browse list. ServerName __Null terminated ASCII server name (up to 16 bytes in length). This name SHOULD be registered with NetBIOS by the server offering the services specified in the Type field. VersionMajor __The major version number of the OS the server is running. it will be returned by NetServerEnum2. VersionMinor __The minor version number of the OS the server is running. This is entirely informational and does not have any significance for the browsing protocol. Type __Specifies the type of the server. The server type bits are specified in the NetServerEnum2 section. Signature __ The browser protocol minor version number in the low 8 bits, the browser protocol major version number in the next higher 8 bits and the signature 0xaa55 in the high 16 bits of this field. Thus, for this version of the browser protocol (1.15) this field has the value 0xaa55010f. This may used to isolate browser servers that are running out of revision browser software; otherwise, it is ignored. Leach, Naik [Page 23] INTERNET-DRAFT CIFS/E Browser Protocol January 10, 1997 Comment __Null terminated ASCII comment for the server. Limited to 43 bytes. When a non-browser server starts up, it announces itself in the manner described once every minute. The frequency of these statements is gradually stretched to once every 12 minutes. Note: older non-browser servers in a domain "D" sent HostAnnouncement frames to the NETBIOS group name D(00). Non-Browser servers supporting version 1.15 of the browsing protocol SHOULD NOT use this NETBIOS name, but for backwards compatibility Master Browsers MAY receive and process HostAnnouncement frames on this name as described above for D(1d). 6.6 AnnouncementRequest Browser Frame When a Master Browser starts up and its browse list is empty, it may force all servers to announce themselves by broadcasting an AnnouncementRequest frame. If the Master Browser serves domain "D", the AnnouncementRequest frame is broadcast using the NETBIOS group name D(00) and mailslot _\MAILSLOT\LANMAN_. The definition of the AnnouncementRequest frame is: struct { unsigned char Opcode; unsigned char ResponseComputerName[]; }; Opcode __Identifies this structure as an announcement request and is defined as AnnounceMent Request with a value of decimal 2. ResponseComputerName __Specifies the name of the computer to send the server announcement to and is up to 16 bytes in length. This is ignored . The response to this browser frame is a HostAnnouncement browser frame as described immediately above. That browser frame does not use this parameter at all. Recipients of this packet should reply by sending an HostAnnouncement frame as described above. The reply should be sent within a randomly determined time period that may have a duration of up to 30 seconds. The random delay ensures that the Master Browser who sent out the packet does not get flooded with replies, all at the same time. 6.7 RequestElection Browser Frame To force the election of a new Master Browser for a domain, any browser client or server can broadcast a RequestElection frame. If the election is for domain "D", the frame is broadcast using the NETBIOS group name D(1e) and mailslot _\MAILSLOT\MSBROWSE_. The definition of the RequestElection frame is: Leach, Naik [Page 24] INTERNET-DRAFT CIFS/E Browser Protocol January 10, 1997 struct { unsigned char Opcode; unsigned char Version; unsigned long Criteria; unsigned long TimeUp; unsigned long MustBeZero; unsigned char ServerName[]; } Opcode __Identifies this structure as an election request, and is defined as RequestElection, with a value of decimal 8. Version __Specifies the version of this election packet. This is a constant and always has the value 0x00010f00 Criteria __Specifies the election criteria of the sender. Produced by OR'ing together the Version and the following: OS info: Windows for Workgroups & Windows 95: 0x00000000 Windows NT: 0x01000000 Windows NT Server: 0x02000000 Role: PDC: 0x00000080 Preferred Master: 0x00000008 Running Master: 0x00000004 Backup Browser which was recently a Master Browser: 0x00000002 Running Backup Browser: 0x00000001 Using NBNS for NETBIOS: 0x00000020 The following masks can be used to isolate parts of the Criteria: Operating System Type Mask 0xFF000000 Election Protocol Version Mask: 0x00FFFF00 Per version criteria mask: 0x000000FF TimeUp __The number of seconds that the server has been up. MustBeZero__Must be zero. ServerName __Null terminated ASCII server name (up to 16 bytes in length). 6.8 Browser Elections All browsers for a domain "D" MUST listen for RequestElection frames on the group name D(1e) and mailslot _\MAILSLOT\MSBROWSE_. Elections proceed in rounds. A round is initiated when a RequestElection frame is sent. When a Browser receives a RequestElection frame, it determines if it has won the round using the following rules: Leach, Naik [Page 25] INTERNET-DRAFT CIFS/E Browser Protocol January 10, 1997 If it has lost an election in the last several seconds, it loses If its election Version is greater than the senders election Version, it wins Else if its election Criteria (including the election version) is greater than the senders Criteria, it wins Else if it has been up longer than the sender, it wins Else if its name is lexically lower than the sender's name, it wins (I.e., at this point, a sever named A will become Master Browser over a server named X) (Note that many browsers which receive a RequestElection frame may win a round.) Each time it wins a round, a browser sends out a RequestElection frame, after a delay based on the browser's current role in the domain: . Master Browsers and Domain Master Browsers delay for 100 ms. . Backup Browsers delay for an amount randomly chosen from the interval 200-600 ms. . All other browsers delay for an amount randomly chosen from the interval 800-3000 ms. If a browser loses a round it drops out of the election by ignoring RequestElection frames until it receives a LocalMasterAnnouncement frame that tells which system is the new Master Browser. If a browser wins 4 rounds in a row, it becomes the Master Browser. 6.9 BecomeBackup Browser Frame If a Local Master Browser for a domain "D" wants to promote a Potential Browser to Backup Browser, it broadcasts a BecomeBackup frame using the NETBIOS group name D(1e) and the _\MAILSLOT\MSBROWSE_ mailslot. The definition of the BecomeBackup frame is: struct { unsigned char Opcode; unsigned char BrowserToPromote[]; } Opcode __ Identifies this structure as a browser server announcement, is defined as BecomeBackup, with a value of decimal 11 BrowserToPromote __Specifies the name of the browser server to be promoted to backup. Maximum of 16 bytes in length. 6.10 LocalMasterAnnouncement Browser Frame A Local Master Browser for a domain announces itself to all the other browsers in its domain that are on its subnet using the LocalMasterAnnouncement frame. If the Local Master Browser serves domain Leach, Naik [Page 26] INTERNET-DRAFT CIFS/E Browser Protocol January 10, 1997 "D", the LocalMasterAnnouncement frame is broadcast using the NETBIOS group name D(1e) and the mailslot _\MAILSLOT\MSBROWSE_. The definition of the LocalMasterAnnouncement frame is: struct { unsigned char Opcode; unsigned char UpdateCount; unsigned long Periodicity; unsigned char ServerName[]; unsigned char VersionMajor; unsigned char VersionMinor; unsigned long Type; unsigned long Signature; unsigned char Comment[]; } where: Opcode __Identifies this structure as a browser server announcement and is defined as LocalMasterAnnouncement with a value of decimal 15. UpdateCount _ must be sent as zero and ignored on receipt. Periodicity __The announcement frequency of the browser (in milliseconds). The browser will be removed from the browse list if it has not been heard from in 3X its announcement frequency. In no case will the server be removed from the browse list before the period 3X has elapsed. Actual implementations may take more than 3X to remove the server from the browse list. ServerName __Null terminated ASCII server name (up to 16 bytes in length). VersionMajor __The major version of the OS the server is running. This value is informational and irrelevant to the browsing protocol. VersionMinor __The minor version of the OS the server is running. This value is informational and irrelevant to the browsing protocol. Type __Specifies the type of the browser. The type bits are specified in the description of NetServerEnum2. Signature __ The browser protocol minor version number in the low 8 bits, the browser protocol major version number in the next higher 8 bits and the signature 0xaa55 in the high 16 bits of this field. This may used to isolate browser servers that are running out of revision browser software; otherwise, it is ignored. Thus, for this version of the browser protocol (1.15) this field has the value 0xaa55010f. Leach, Naik [Page 27] INTERNET-DRAFT CIFS/E Browser Protocol January 10, 1997 Comment __Null terminated ASCII comment for the browser. Limited to 43 bytes. Local Master Browsers do not need to send HostAnnouncement frames; the LocalMasterAnnouncement accomplishes that function. 6.11 MasterAnnouncement browser Frame The MasterAnnouncement frame is sent by a Local Master Browser to the Domain Master Browser, which runs on the PDC. If the name of the PDC is "PDCName", then the MasterAnnouncement frame is sent to the NETBIOS unique name PDCName(00) and mailslot _\MAILSLOT\MSBROWSE_. Appendix B describes how to determine the name of the Primary Domain Controller. The definition of the MasterAnnouncement frame is:: struct { unsigned char Opcode; unsigned char MasterBrowserServerName[]; }; Opcode __Identifies this structure as a master browser server announcement and is defined as MasterAnnouncement with a value of decimal 13. MasterBrowserServerName __Specifies the name of the master browser server (up to 16 bytes in length). 6.12 DomainAnnouncement Browser Frame Master Browsers (including Local Master Browsers and Domain Master Browsers) announce the domain they serve to any other Master Browsers on their subnet by broadcasting a DomainAnnouncement frame using the NETBIOS group name _(01)(02)__MSBROWSE__(02)(01)_ and mailslot _\MAILSLOT\MSBROWSE_. The definition of the DomainAnnouncement frame is: struct { unsigned char Opcode; unsigned char UpdateCount; unsigned long Periodicity; unsigned char DomainName[]; unsigned char VersionMajor; unsigned char VersionMinor; unsigned long Type; unsigned long Signature; unsigned char MasterBrowserName[]; } where: Opcode __Identifies this structure as a browser server announcement and is defined as DomainAnnouncement with a value of decimal 12. Leach, Naik [Page 28] INTERNET-DRAFT CIFS/E Browser Protocol January 10, 1997 UpdateCount _ must be sent as zero and ignored on receipt. Periodicity __The announcement frequency of the domain (in milliseconds). The domain will be removed from the browse list if it has not been heard from in 3X its announcement frequency. In no case will the domain be removed from the browse list before the period 3X has elapsed. Actual implementations may take more than 3X to actually remove the domain from the browse list. DomainName __Null terminated ASCII server name (up to 16 bytes in length). VersionMajor __The major version of the OS the server is running. This value is informational and irrelevant to the browsing protocol. VersionMinor __The minor version of the OS the server is running. This value is informational and irrelevant to the browsing protocol. Type __Specifies the type of the server. The server type bits are specified in the previous section. Signature __ The browser protocol minor version number in the low 8 bits, the browser protocol major version number in the next higher 8 bits and the signature 0xaa55 in the high 16 bits of this field. This may used to isolate browser servers that are running out of revision browser software; otherwise, it is ignored. Thus, for this version of the browser protocol (1.15) this field has the value 0xaa55010f. MasterBrowserName __Null terminated ASCII string containing the name of the master browser server for this domain. 7. References [CIFS 96} I. Heizer, P. Leach, D. Perry, "Common Internet Files System Protocol (CIFS/1.0)", Internet-Draft, ,June 30, 1996 . (Work in Progress) [RFC 1001] K. Auerbach, A. Aggarwal, "Protocol Standard for a NETBIOS Service on a TCP/UDP Transport: Concepts and Methods", RFC 1001, Epilogue Technology, March 1987. [Bradner 96] S. Bradner, ""Key words for use in RFCs to Indicate Requirement Levels", Internet-Draft, , August 1996 (Work in Progress) 8. Author's Addresses Paul Leach Dilip Naik Microsoft 1 Microsoft Way Leach, Naik [Page 29] INTERNET-DRAFT CIFS/E Browser Protocol January 10, 1997 Redmond, WA 98052 paulle@microsoft.com v-dilipn@microsoft.com 9. Appendix A - Multi-net considerations To begin with, let's clearly define what is meant by multiple networks here. A computer can be running one or more network protocols on a single network adapter card such as IP and IPX. Each of these is considered to be a _network_ for the purposes of this paragraph. A computer could also have multiple network adapter cards, and there could be different protocols running on the different adapter cards, or even the same protocol(s) on all of the adapter cards. So, more precisely, a network here means a transport protocol per adapter card. A computer with 2 physical network cards, running 2 different transport protocols on each network card, would have 4 logical networks. Browsers need to remember which logical network a server is located on. When a client queries a browser for a list of servers, the browser server needs to return a list of servers that are on the same logical network on which the client query arrived at the browser server. So a client that sends a browser frame using say IP will only be returned information about servers that sent announcements using IP. To summarize, browser servers need to understand the concept of logical networks and track server announcements as well as client queries on a per logical network basis. 10. Appendix B - Primary Domain Controller Location Protocol This appendix details how a client goes about locating a Primary Domain Controller (PDC). The process is rather involved, because different versions of the PDC have used different versions of the protocol, and hence a client that does not know what protocol is supported by its PDC has to try them all. A Primary Domain Controller (PDC) for a domain "D" is located by sending a mailslot message containing a NETLOGON_QUERY frame to a NETBIOS name and mailslot "\NET\NETLOGON" and then waiting for a reply mailslot message, which will be sent to the mailslot name specified by the client in the NETLOGON_QUERY structure., and which will contain a NETLOGON_RESPONSE structure. If there is no response after a delay, the message may be retransmitted. The delay MUST be at least twice the expected service time, and the delay should be doubled after each time- out. If a reply is received, the name of the PDC SHOULD be cached for future use, so as time minimize network traffic. If no reply is received after several retransmissions, the PDC may be declared to be unreachable, and no further attempt to locate it should be made for a while (exactly how long depends on the expected recovery time for a PDC and/or for the network; typically a minute or so, but should be increased after each failure). Leach, Naik [Page 30] INTERNET-DRAFT CIFS/E Browser Protocol January 10, 1997 The only difference between versions of the protocol is the NETBIOS name to which the message is sent, as follows: NETBIOS name PDC's OS version name type ============= =========== ======== D(1b) unique Windows NT 3.51 or later or compatible D(1c) group Windows NT 3.1 or later or compatible D(00) group all Clients which are configured to know or are willing to assume what version of the protocol their PDC is running may directly use the appropriate NETBIOS name for that version. Otherwise, they SHOULD first attempt D(1b), since it is unicast and creates the least network traffic; if there is no response, then they SHOULD try the others. They MAY try them in parallel. The NETLOGON_QUERY structure is defined as : struct NETLOGON_QUERY{ unsigned char Opcode; char ComputerName[]; char MailslotName[]; unsigned short Lm20Token; } ; Opcode __Identifies this structure as a NETLOGON_QUERY and has a value of 0x07. ComputerName __Specifies the ASCII name of the computer sending the query, and is up to 16 bytes in length. The response is sent to NETBIOS unique name (00). MailslotName __Specifies the ASCII name of the mailslot to which the response is to be sent, and is up to 256 bytes in length; cannot be _\MAILSLOT\LANMAN_ or _\MAILSLOT\MSBROWSE_ or "\NET\NETLOGON". Lm20Token - has a value of 0xFFFF. The response mailslot message contains a NETLOGON_RESPONSE data structure that is defined as the following for non Windows NT clients: struct NETLOGON_RESPONSE { unsigned char Opcode; char PrimaryDCName[16]; unsigned short Lm20Token; }; where Opcode __Identifies this structure as a NETLOGON_RESPONSE and has a value of 0x12. Leach, Naik [Page 31] INTERNET-DRAFT CIFS/E Browser Protocol January 10, 1997 PrimaryDCName __Specifies the ASCII name of the Primary Domain Controller and is up to 16 bytes in length. Lm20Token - has a value of 0xFFFF Note that this procedure to locate a Primary Domain Controller is expensive in terms of network traffic. The Microsoft implementations attempt to alleviate this by caching the PDC Name. Before using the cached PDC Name, a NetServerEnum2 API is remoted to the PDC and a sanity check is performed to ensure that the server type returned indicates a Primary Domain Controller 11. Appendix C - Summary of Special NETBIOS Names This section details the various NETBIOS names that are involved in sending and receiving browser frames. The different mailslots involved in browsing (there are only 3) are described later on when the browser frames are detailed. 11.1 Registered unique names (00) This name is used by all servers and clients to receive second class mailslot messages. A system must add this name in order to receive mailslot messages. The only browser requests that should appear on this name are BecomeBackup, GetBackupListResp, MasterAnnouncement, and LocalMasterAnnouncement frames. All other datagrams (other than the expected non-browser datagrams) may be ignored and an error logged. (1d) This name is used to identify a master browser server for domain "DOMAIN" on a subnet. A master browser server adds this name as a unique NETBIOS name when it becomes master browser. If the attempt to add the name fails, the master browser server assumes that there is another master in the domain and will fail to come up. It may log an error if the failure occurs more than 3 times in a row (this either indicates some form of network misconfiguration or a software error). The only requests that should appear on this name are GetBackupListRequest and HostAnnouncement requests. All other datagrams on this name may be ignored (and an error logged). If running a NETBIOS name service (NBNS, such as WINS), this name should not be registered with the NBNS. (1b) This name is used to identify the Domain Master Browser for domain "DOMAIN" (which is also the primary domain controller). It is a unique name added only by the primary domain controller. The primary domain controller will respond to GetBackupListRequest on this name just as it responds to these requests on the (1d) name. Leach, Naik [Page 32] INTERNET-DRAFT CIFS/E Browser Protocol January 10, 1997 11.2 Registered group names (01)(02)__MSBROWSE__(02)(01) This name is used by Master Browsers to announce themselves to the other Master Browsers on a subnet. It is added as a group name by all Master Browser servers. The only broadcasts that should appear on this name is DomainAnnouncement requests. All other datagrams can be ignored. (00) This name is used by clients and servers in domain "DOMAIN" to process server announcements. The only requests that should appear on this name that the browser is interested in are AnnouncementRequest and NETLOGON_QUERY (to locate the PDC) packets. All other unidentifiable requests may be ignored (and an error logged). (1e) This name is used for announcements to browsers for domain "DOMAIN" on a subnet. This name is registered by all the browser servers in the domain. The only requests that should appear on this name are RequestElection and AnnouncementRequest packets. All other datagrams may be ignored (and an error logged). (1c) This name is registered by Primary Domain Controllers. 12. Appendix D - Browsing Protocol Evolution This Appendix details how the Microsoft Browser specification evolved and correlates the evolution to specific Microsoft products. The first browser implementation was with Lan Manager 1.0. Here, there were no browser servers as such. Each client acted as its own browser server. All servers announced themselves by means of datagrams and every client and server listened for those datagrams. Obviously, the amount of browser datagram traffic is fairly high and scales extremely poorly with an increase in the number of servers. The next major revision in the browser specification was with Windows For Workgroups. This is where the concept of a browser server was really introduced. Windows NT 3.51 expanded upon what Windows For Workgroups built. Windows NT 3.51 introduced the special NETBIOS name (1b) that is registered with WINS. Windows NT 3.51 also shipped a new redirector for Windows For Workgroups that could take advantage of this new (1b) name. In a domain which spans multiple broadcast areas, it may be necessary to have a configuration file available that can resolve the address of a browser server. This is because browsers rely on broadcasts for name resolution, for historical reasons. But these name resolution broadcast Leach, Naik [Page 33] INTERNET-DRAFT CIFS/E Browser Protocol January 10, 1997 packets are not forwarded by routers that span the multiple broadcast areas of a domain. One example of such a configuration file is the LMHOSTS file on Windows NT machines. Leach, Naik [Page 34]