idnits 2.17.1 draft-leach-cifs-browser-spec-00.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** Cannot find the required boilerplate sections (Copyright, IPR, etc.) in this document. Expected boilerplate is as follows today (2024-04-24) according to https://trustee.ietf.org/license-info : IETF Trust Legal Provisions of 28-dec-2009, Section 6.a: This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79. IETF Trust Legal Provisions of 28-dec-2009, Section 6.b(i), paragraph 2: Copyright (c) 2024 IETF Trust and the persons identified as the document authors. All rights reserved. IETF Trust Legal Provisions of 28-dec-2009, Section 6.b(i), paragraph 3: This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- ** Missing expiration date. The document expiration date should appear on the first and last page. ** The document seems to lack a 1id_guidelines paragraph about Internet-Drafts being working documents. ** The document seems to lack a 1id_guidelines paragraph about the list of current Internet-Drafts. ** The document seems to lack a 1id_guidelines paragraph about the list of Shadow Directories. == The page length should not exceed 58 lines per page, but there was 33 longer pages, the longest (page 2) being 61 lines Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The document seems to lack a Security Considerations section. ** The document seems to lack an IANA Considerations section. (See Section 2.2 of https://www.ietf.org/id-info/checklist for how to handle the case when there are no actions for IANA.) ** The document seems to lack separate sections for Informative/Normative References. All references will be assumed normative when checking for downward references. ** There is 1 instance of too long lines in the document, the longest one being 15 characters in excess of 72. ** The document seems to lack a both a reference to RFC 2119 and the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords. RFC 2119 keyword, line 135: '...nal RFC keywords MUST, SHOULD, etc., (...' RFC 2119 keyword, line 343: '...A browser client SHOULD keep a list of...' RFC 2119 keyword, line 344: '...domain; it MAY cache lists of Backup B...' RFC 2119 keyword, line 349: '...A browser client SHOULD distribute its...' RFC 2119 keyword, line 354: '...A browser client SHOULD NOT send its N...' (61 more instances...) Miscellaneous warnings: ---------------------------------------------------------------------------- == Line 42 has weird spacing: '...1.15 of the...' == Line 44 has weird spacing: '...it (and is th...' == Line 131 has weird spacing: '...1.15 of the b...' == Line 132 has weird spacing: '...it (and is th...' == Line 178 has weird spacing: '...various activ...' == (7 more instances...) -- The document seems to lack a disclaimer for pre-RFC5378 work, but may have content which was first submitted before 10 November 2008. If you have contacted all the original authors and they are all willing to grant the BCP78 rights to the IETF Trust, then this is fine, and you can ignore this comment. If not, you may need to add the pre-RFC5378 disclaimer. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (January 10, 1997) is 9966 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- == Missing Reference: 'CIFS 96' is mentioned on line 149, but not defined -- Looks like a reference, but probably isn't: '0' on line 708 -- Looks like a reference, but probably isn't: '30' on line 415 -- Looks like a reference, but probably isn't: '1' on line 709 -- Looks like a reference, but probably isn't: '2' on line 710 == Missing Reference: 'RFC 1002' is mentioned on line 719, but not defined -- Looks like a reference, but probably isn't: '69' on line 767 -- Looks like a reference, but probably isn't: '79' on line 767 -- Looks like a reference, but probably isn't: '65' on line 767 -- Looks like a reference, but probably isn't: '64' on line 767 -- Looks like a reference, but probably isn't: '82' on line 767 -- Looks like a reference, but probably isn't: '20' on line 767 -- Looks like a reference, but probably isn't: '15' on line 767 -- Looks like a reference, but probably isn't: '16' on line 1531 Summary: 10 errors (**), 0 flaws (~~), 9 warnings (==), 14 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 1 Network Working Group Paul J. Leach, Microsoft 2 INTERNET-DRAFT Dilip C. Naik, Microsoft 3 draft-leach-cifs-browser-spec-00.txt 4 Category: Informational 5 Expires June 10, 1997 January 10, 1997 7 CIFS/E Browser Protocol 8 Preliminary Draft 10 STATUS OF THIS MEMO 12 THIS IS A PRELIMINARY DRAFT OF AN INTERNET-DRAFT. IT DOES NOT REPRESENT 13 THE CONSENSUS OF ANY WORKING GROUP. 15 This document is an Internet-Draft. Internet-Drafts are working 16 documents of the Internet Engineering Task Force (IETF), its areas, and 17 its working groups. Note that other groups may also distribute working 18 documents as Internet-Drafts. 20 Internet-Drafts are draft documents valid for a maximum of six months 21 and may be updated, replaced, or obsoleted by other documents at any 22 time. It is inappropriate to use Internet-Drafts as reference material 23 or to cite them other than as "work in progress". 25 To learn the current status of any Internet-Draft, please check the 26 "1id-abstracts.txt" listing contained in the Internet-Drafts Shadow 27 Directories on ftp.is.co.za (Africa), nic.nordu.net (Europe), 28 munnari.oz.au (Pacific Rim), ds.internic.net (US East Coast), or 29 ftp.isi.edu (US West Coast). 31 Distribution of this document is unlimited. Please send comments to the 32 authors or the CIFS mailing list at . Discussions 33 of the mailing list are archived at 34 . 36 ABSTRACT 38 The CIFS/E (CIFS extensions for enterprise networks) family of protocols 39 includes a protocol for browsing. Browsing is a mechanism for 40 discovering servers that are running particular services (not just CIFS 41 file services). Servers are organized into named groups called domains, 42 which form browsing scopes. This document specifies version 1.15 of the 43 browsing protocol. It also specifies the mailslot protocol, because the 44 browsing protocol depends on it (and is the only CIFS/E protocol which 45 does). 47 Table of Contents 49 1. INTRODUCTION........................................................3 51 2. PREREQUISITES.......................................................3 53 3. BROWSER OVERVIEW....................................................3 55 4. BROWSING PROTOCOL ARCHITECTURE......................................5 57 4.1 LAYERING OF BROWSING PROTOCOL REQUESTS ...........................5 59 4.2 BROWSER CLIENT ...................................................7 61 4.3 NON-BROWSER SERVER ...............................................8 63 4.4 BROWSER SERVERS ..................................................9 65 4.4.1 Potential Browser Server ......................................9 67 4.4.2 Backup Browser ................................................9 69 4.4.3 Master Browser ...............................................10 71 4.4.4 Domain Master Browser ........................................13 73 5. MAILSLOT PROTOCOL SPECIFICATION....................................13 75 6. BROWSER PROTOCOL SPECIFICATION.....................................15 77 6.1 NETBIOS NAME NOTATION ...........................................15 79 6.2 GETB L ACKUP ISTREQUEST BROWSER FRAME ..............................16 81 6.3 GETBACKUPLISTRESPONSE BROWSER FRAME .............................16 83 6.4 THE NETSERVERENUM2 RAP SERVICE ..................................17 85 6.4.1 Transaction Request Parameters section .......................18 87 6.4.2 Transaction Request Data section .............................19 88 6.4.3 Transaction Response Parameters section ......................19 90 6.4.4 Transaction Response Data section ............................20 92 6.5 HOSTANNOUNCEMENT BROWSER FRAME ..................................21 94 6.6 ANNOUNCEMENTREQUEST BROWSER FRAME ...............................22 96 6.7 REQUESTELECTION BROWSER FRAME ...................................23 98 6.8 BROWSER ELECTIONS ...............................................24 100 6.9 BECOMEBACKUP BROWSER FRAME ......................................25 102 6.10 LOCALMASTERANNOUNCEMENT BROWSER FRAME ..........................25 104 6.11 MASTERANNOUNCEMENT BROWSER FRAME ...............................27 106 6.12 DOMAINANNOUNCEMENT BROWSER FRAME ...............................27 108 7. REFERENCES.........................................................28 110 8. AUTHOR'S ADDRESSES.................................................28 112 9. APPENDIX A - MULTI-NET CONSIDERATIONS..............................29 114 10. APPENDIX B - PRIMARY DOMAIN CONTROLLER LOCATION PROTOCOL..........29 116 11. APPENDIX C - SUMMARY OF SPECIAL NETBIOS NAMES.....................31 118 11.1 REGISTERED UNIQUE NAMES ........................................31 120 11.2 REGISTERED GROUP NAMES .........................................32 122 12. APPENDIX D - BROWSING PROTOCOL EVOLUTION..........................32 124 1. Introduction 126 The CIFS/E (CIFS extensions for enterprise networks) family of protocols 127 includes a protocol for "browsing". Browsing is a mechanism for 128 discovering servers that are running particular services (not just CIFS 129 file services). Servers are organized into named groups called 130 "domains", which form browsing scopes. This document specifies version 131 1.15 of the browsing protocol. It also specifies the mailslot protocol, 132 because the browsing protocol depends on it (and is the only CIFS/E 133 protocol which does). 135 This document uses the traditional RFC keywords MUST, SHOULD, etc., (now 136 documented in [Bradner 96]) to indicate requirement levels for 137 interoperability. 139 Note: This document is about CIFS/E browsers and has nothing to do 140 whatsoever with Web browsers such as Internet Explorer and Netscape 141 Navigator. This is a specification for persons interested in 142 implementing a browser server or client that can inter-operate with 143 other CIFS/E browsers and clients. 145 2. Prerequisites 147 . Familiarity with Common Internet File System specification (CIFS) in 148 general and the Transact2 SMB as well as Remote Administration 149 Protocol in particular [CIFS 96] 150 . Familiarity with concepts of subnets and NETBIOS [RFC 1001]. 152 Additional information about browsing may be found in the MSDN articles 153 _Browsing and Windows 95_ Parts I, II and III. These articles cover 154 considerations for browser deployment, especially in a WAN environment. 156 3. Browser Overview 158 Hosts involved in the browsing process can be separated into two 159 distinct groups, browser clients and browser servers (often referred to 160 simply as _browsers_). 162 A browser is a server which maintains information about servers _ 163 primarily the domain they are in and the services that they are running 164 -- and about domains. Browsers may assume several different roles in 165 their lifetimes, and dynamically switch between them. 167 Browser clients are of two types: workstations and (non-browser) 168 servers. In the context of browsing, workstations query browsers for the 169 information they contain; servers supply browsers the information by 170 registering with them. Note that, at times, browsers may themselves 171 behave as browser clients and query other browsers. 173 For the purposes of this specification, a domain is simply a name with 174 which to associate a group of resources such as computers, servers and 175 users. Domains allow a convenient means for browser clients to restrict 176 the scope of a search when they query browser servers. Every domain has 177 a _master_ server called the Primary Domain Controller (PDC) that 178 manages various activities within the domain. 180 One browser for each domain on a subnet is designated the Local Master 181 Browser for that domain. Servers in its domain on the subnet register 182 with it, as do the Local Master Browsers for other domains on the 183 subnet. It uses these registrations to maintain authoritative 184 information about its domain on its subnet. If there are other subnets 185 in the network, it also knows the name of the server running the 186 domain's Domain Master Browser; it registers with it, and uses it to 187 obtain information about the rest of the network (see below). 189 Clients on a subnet query browsers designated as the Backup Browsers for 190 the subnet (not the Master Browser). Backup Browsers maintain a copy of 191 the information on the Local Master Browser; they get it by periodically 192 querying the Local Master Browser for all of its information. Clients 193 find the Backup Browsers by asking the Local Master Browser. Clients are 194 expected to spread their queries evenly across Backup Browsers to 195 balance the load. 197 The Local Master Browser is dynamically elected automatically. Multiple 198 Backup Browser Servers may exist per subnet; they are selected from 199 among the potential browser servers by the Local Master Browser, which 200 is configured to select enough to handle the expected query load. 202 When the re are multiple subnets, a Domain Master Browser is assigned 203 the task of keeping the multiple subnets in synchronization. The Primary 204 Domain Controller (PDC) always acts as the Domain Master Browser. The 205 Domain Master Browser periodically acts as a client and queries all the 206 Local Master Browsers for its domain, asking them for a list containing 207 all the domains and all the servers in their domain known within their 208 subnets; it merges all the replies into a single master list. This 209 allows a Domain Master Browser server to act as a collection point for 210 inter-subnet browsing information. Local Master Browsers periodically 211 query the Domain Master Browser to retrieve the network-wide information 212 it maintains. 214 When a domain spans only a single subnet, there will not be any distinct 215 Local Master Browser; this role will be handled by the Domain Master 216 Browser. Similarly, the Domain Master Browser is always the Local Master 217 Browser for the subnet it is on. 219 When a browser client suspects that the Local Master Browser has failed, 220 the client will instigate an election in which the browser servers 221 participate, and some browser servers may change roles. 223 Some characteristics of a good browsing mechanism include: 224 . minimal network traffic 225 . minimum server discovery time 226 . minimum change discovery latency 227 . immunity to machine failures 229 Historically, Browser implementations had been very closely tied to 230 NETBIOS and datagrams. The early implementations caused a lot of 231 broadcast traffic. See Appendix D for an overview that presents how the 232 Browser specification evolved. 234 4. Browsing Protocol Architecture 236 This section first describes the how the browsing protocol is layered, 237 then describes the roles of clients, servers, and browsers in the 238 browsing subsystem. 240 4.1 Layering of Browsing Protocol Requests 242 Most of the browser functionality is implemented using mailslots. 243 Mailslots provide a mechanism for fast, unreliable unidirectional data 244 transfer; they are named via ASCII _mailslot (path) name_. Mailslots are 245 implemented using the CIFS Transact SMB which is encapsulated in a 246 NETBIOS datagram. Browser protocol requests are sent to browser specific 247 mailslots using some browser-specific NETBIOS names. These datagrams can 248 either be unicast or broadcast, depending on whether the NETBIOS name is 249 a _unique name_ or a _group name_. Various data structures, which are 250 detailed subsequently within this document, flow as the data portion of 251 the Transact SMB. 253 Here is an example of a generic browser SMB, showing how a browser 254 request is encapsulated in a TRANSACT SMB request. Note that the PID, 255 TID, MID, UID, and Flags are all 0 in mailslot requests. 257 SMB: C transact, File = \MAILSLOT\BROWSE 258 SMB: SMB Status = Error Success 259 SMB: Error class = No Error 260 SMB: Error code = No Error 261 SMB: Header: PID = 0x0000 TID = 0x0000 MID = 0x0000 UID = 0x0000 262 SMB: Tree ID (TID) = 0 (0x0) 263 SMB: Process ID (PID) = 0 (0x0) 264 SMB: User ID (UID) = 0 (0x0) 265 SMB: Multiplex ID (MID) = 0 (0x0) 266 SMB: Flags Summary = 0 (0x0) 267 SMB: Command = C transact 268 SMB: Word count = 17 269 SMB: Word parameters 270 SMB: Total parm bytes = 0 271 SMB: Total data bytes = 33 272 SMB: Max parm bytes = 0 273 SMB: Max data bytes = 0 274 SMB: Max setup words = 0 275 SMB: Transact Flags Summary = 0 (0x0) 276 SMB: ...............0 = Leave session intact 277 SMB: ..............0. = Response required 278 SMB: Transact timeout = 0 (0x0) 279 SMB: Parameter bytes = 0 (0x0) 280 SMB: Parameter offset = 0 (0x0) 281 SMB: Data bytes = 33 (0x21) 282 SMB: Data offset = 86 (0x56) 283 SMB: Setup word count = 3 284 SMB: Setup words 285 SMB: Mailslot opcode = Write mailslot 286 SMB: Transaction priority = 1 287 SMB: Mailslot class = Unreliable (broadcast) 288 SMB: Byte count = 50 289 SMB: Byte parameters 290 SMB: Path name = \MAILSLOT\BROWSE 291 SMB: Transaction data 292 SMB: Data: Number of data bytes remaining = 33 (0x0021) 294 Note the SMB command is Transact, the opcode within the Transact SMB is 295 Mailslot Write, and the browser data structure is carried as the 296 Transact data. 297 The Transaction data begins with an opcode, that signifies the operation 298 and determines the size and structure of data that follows. This opcode 299 is named as per one of the below: 301 HostAnnouncement 1 302 AnnouncementRequest 2 303 RequestElection 8 304 GetBackupListReq 9 305 GetBackupListResp 10 306 BecomeBackup 11 307 DomainAnnouncment 12 308 MasterAnnouncement 13 309 LocalMasterAnnouncement 15 310 Browser datagrams are often referred to as simply browser frames. The 311 frames are in particular, referred to by the name of the opcode within 312 the Transaction data e.g. a GetBackupListReq browser frame, a 313 RequestElection browser frame, etc. 315 The structures that are sent as the data portion of the Transact SMB are 316 described in section(s) 6.2 through 6.12 in this document. These 317 structures are tightly packed, i.e. there are no intervening pad bytes 318 in the structure, unless they are explicitly described as being there. 319 All quantities are sent in native Intel format and multi-byte values are 320 transmitted least significant byte first. 322 Besides mailslots and Transaction SMBs, the other important piece of the 323 browser architecture is the NetServerEnum2 request. This request that 324 allows an application to interrogate a Browser Server and obtain a 325 complete list of resources (servers, domains, etc) known to that Browser 326 server. Details of the NetServerEnum2 request are presented in section 327 6.4. Some examples of the NetServerEnum2 request being used are when a 328 Local Master Browser sends a NetServerEnum2 request to the Domain Master 329 Browser and vice versa. Another example is when a browser client sends a 330 NetServerEnum2 request to a Backup Browser server. 332 4.2 Browser Client 334 A browser client is a system running applications which may wish to 335 query for a list of servers for a particular domain (often its own) or a 336 list of all the domains in the network. (For example, such an 337 application is launched when a user clicks on the Network Neighborhood 338 icon on a Windows machine.) A browser client may send a NetServerEnum2 339 request (see section 6.4) to any Backup Browser serving that domain to 341 obtain such information. 343 A browser client SHOULD keep a list of a few Backup Browsers for its own 344 domain; it MAY cache lists of Backup Browsers for other domains if it 345 browses them frequently, or it may obtain them upon demand. The 346 objective is to minimize the cost of locating Backup Browsers each time 347 it wants to make a NetServerEnum2 request. 349 A browser client SHOULD distribute its NetServerEnum2 requests randomly 350 among all the Backup Browsers for a domain in its list. The objective is 351 to enable multiple Backup Browsers to effectively handle high browsing 352 loads. 354 A browser client SHOULD NOT send its NetServerEnum2 requests directly to 356 a Master Browser. Browser clients unilaterally sending NetServerEnum2 358 requests directly to Master Browsers will result in unavoidable 360 congestive collapse in a large enough network. 362 A browser client can locate browser servers for the domain it wants to 363 browse by sending a GetBackupListRequest frame to the Local Master 364 Browser for that domain and waiting for a GetBackupListResponse frame. 365 See section 6.2 and section 6.3, respectively. Once the Local Master 366 Browser server responds with a list of Backup Browser servers, the 367 client should choose several at random from within the response, and 368 cache them. If there is no response after a delay, the 369 GetBackupListRequest frame may be retransmitted. The delay MUST be at 370 least twice the expected service time, and the delay should be doubled 371 after each time-out. 373 In case the Local Master Browser for a domain fails to respond to the 375 GetBackupListRequest, the browser client may attempt to retrieve a list 377 of Backup Browsers by sending a GetBackupListRequest frame directly to 379 the Domain Master Browser for that domain. It can find the Domain Master 381 Browser using the method described in appendix B. 383 A browser client SHOULD force an election by sending a RequestElection 384 frame (see section 6.7) if it does not get a response to a 386 GetBackupListRequest for its own domain after several retransmissions, 387 since it must be assumed that the Local Master browser has crashed. 388 Details of the election process are in sections 6.7 and 6.8. 390 4.3 Non-Browser Server 392 A non-browser server is a server that has some resource(s) or service(s) 393 it wishes to advertise as being available using the browsing protocol. 394 Examples of non-browser servers would be an SQL server, print server, 395 etc. 397 A non-browser server MUST periodically send a HostAnnouncement browser 398 frame, specifying the type of resources or services it is advertising. 399 Details are in section 6.5. 401 A non-browser server SHOULD announce itself relatively frequently when 402 it first starts up in order to make its presence quickly known to the 403 browsers and thence to potential clients. The frequency of the 404 announcements SHOULD then be gradually stretched, so as to minimize 405 network traffic. Typically, non-browser servers announce themselves 406 once every minute upon start up and then gradually adjust the frequency 407 of the announcements to once every 12 minutes. 409 A non-browser server SHOULD send a HostAnnouncement browser frame 410 specifying a type of 0 just prior to shutting down, to allow it to 411 quickly be removed from the list of available servers. 413 A non-browser server MUST receive and process AnnouncementRequest frames 414 from the Local Master Browser, and MUST respond with a HostAnnouncement 415 frame, after a delay chosen randomly from the interval [0,30] seconds. 416 AnnouncementRequests typically happen when a Local Master Browser starts 417 up with an empty list of servers for the domain, and wants to fill it 418 quickly. The 30 second range for responses prevents the Master Browser 419 from becoming overloaded and losing replies, as well as preventing the 420 network from being flooded with responses. 422 4.4 Browser Servers 424 The following sections describe the roles of the various types of 425 browser servers. 427 4.4.1 Potential Browser Server 429 A Potential Browser server is a browser server that is capable of being 430 a Backup Browser server or Master Browser server, but is not currently 431 fulfilling either of those roles. 433 A Potential Browser MUST set type SV_TYPE_POTENTIAL_BROWSER (see section 434 6.4.1) in its HostAnnouncement until it is ready to shut down. In its 436 last HostAnnouncement frame before it shuts down, it SHOULD specify a 437 type of 0. 439 A Potential Browser server MUST receive and process BecomeBackup frames 440 (see section 6.9) and become a backup browser upon their receipt. 442 A Potential Browser MUST participate in browser elections (see section 443 6.8). 445 4.4.2 Backup Browser 447 Backup Browser servers are a subset of the Potential Browsers that have 448 been chosen by the Master Browser on their subnet to be the Backup 449 Browsers for the subnet. 451 A Backup Browser MUST set type SV_TYPE_BACKUP_BROWSER (see section 452 6.4.1) in its HostAnnouncement until it is ready to shut down. In its 454 last HostAnnouncement frame before it shuts down, it SHOULD specify a 455 type of 0. 457 A Backup Browser MUST listen for a LocalMasterAnnouncement frame (see 458 section 6.10) from the Local Master Browser, and use it to set the name 460 of the Master Browser it queries for the server and domain lists. 462 A Backup Browsers MUST periodically make a NetServerEnum2 request of 463 the Master Browser on its subnet for its domain to get a list of servers 464 in that domain, as well as a list of domains. The period is a 465 configuration option balancing currency of the information with network 466 traffic costs _ a typical value is 15 minutes. 468 A Backup Browser SHOULD force an election by sending a RequestElection 469 frame (see section 6.7) if it does not get a response to its periodic 471 NetServeEnum2 request to the Master Browser. 473 A Backup Browser MUST receive and process NetServerEnum2 requests from 474 browser clients, for its own domain and others. If the request is for a 475 list of servers in its domain, or for a list of domains, it can answer 476 from its internal lists. If the request is for a list of servers in a 477 domain different than the one it serves, it sends a NetServerEnum2 478 request to the Domain Master Browser for that domain (which it can in 479 find in its list of domains and their Domain Master Browsers). 481 A Backup Browser MUST participate in browser elections (see section 482 6.8). 484 4.4.3 Master Browser 486 Master Browsers are responsible for: 487 . indicating it is a Master Browser 488 . receiving server announcements and building a list of such servers 489 and keeping it reasonably up-to-date. 490 . returning lists of Backup Browsers to browser clients. 491 . ensuring an appropriate number of Backup Browsers are available. 492 . announcing their existence to other Master Browsers on their subnet, 493 to the Domain Master Browser for their domain, and to all browsers in 494 their domain on their subnet 495 . forwarding requests for lists of servers on other domains to the 496 Master Browser for that domain 497 . keeping a list of domains in its subnet 498 . synchronizing with the Domain Master Browser (if any) for its domain 499 . participating in browser elections 500 . ensuring that there is only one Master Browser on its subnet 502 A Master Browser MUST set type SV_TYPE_MASTER_BROWSER (see section 503 6.4.1) in its HostAnnouncement until it is ready to shut down. In its 505 last HostAnnouncement frame before it shuts down, it SHOULD specify a 506 type of 0. 508 A Master Browser MUST receive and process HostAnnouncement frames from 509 servers, adding the server name and other information to its servers 510 list; it must mark them as _authoritative_ entries. Periodically, it 512 MUST check all local server entries to see if a server's 513 HostAnnouncement has timed out (no HostAnnouncement received for three 514 times the periodicity the server gave in the last received 515 HostAnnouncement) and remove timed-out servers from its list. 517 A Master Browser MUST receive and process DomainAnnouncement frames (see 518 section 6.12) and maintain the domain names and their associated (Local) 520 Master Browsers in its internal domain list until they time out; it must 521 mark these as _authoritative_ entries. Periodically, it MUST check all 523 local domain entries to see if a server's DomainAnnouncement has timed 524 out (no DomainAnnouncement received for three times the periodicity the 525 server gave in the last received DomainAnnouncement) and remove timed- 526 out servers from its list. 528 A Master Browser MUST receive and process GetBackupListRequest frames 529 from clients, returning GetBackupListResponse frames containing a list 530 of the Backup Servers for its domain. 532 A Master Browser MUST eventually send BecomeBackup frames (see section 533 6.9) to one or more Potential Browser servers to increase the number of 534 Backup Browsers if there are not enough Backup Browsers to handle the 535 anticipated query load. Note: possible good times for checking for 536 sufficient backup browsers are after being elected, when timing out 537 server HostAnnouncements, and when receiving a server's HostAnnouncement 538 for the first time. 540 A Master Browser MUST periodically announce itself and the domain it 541 serves to other (Local) Master Browsers on its subnet, by sending a 542 DomainAnnouncement frame (see section 6.12) to its subnet. 544 A Master Browser MUST send a MasterAnnouncement frame (see section 6.11) 545 to the Domain Master Browser after it is first elected, and periodically 546 thereafter. This informs the Domain Master Browser of the presence of 547 all the Master Browsers. 549 A Master Browser MUST periodically announce itself to all browsers for 550 its domain on its subnet by sending a LocalMasterAnnouncement frame (see 551 section 6.10). 553 A Master Browser MUST receive and process NetServerEnum2 requests from 554 browser clients, for its own domain and others. If the request is for a 555 list of servers in its domain, or for a list of domains, it can answer 556 from its internal lists. Entries in its list marked _authoritative_ MUST 558 have the SV_TYPE_LOCAL_LIST_ONLY bit set in the returned results; it 559 must be clear for all other entries. If the request is for a list of 560 servers in a domain different than the one it serves, it sends a 561 NetServerEnum2 request to the Domain Master Browser for that domain 562 (which it can in find in its list of domains and their Domain Master 563 Browsers). 565 Note: The list of servers that the Master Browser maintains and 566 returns to the Backup Browsers, is limited in size to 64K of 567 data. This will limit the number of systems that can be in a 568 browse list in a single workgroup or domain to approximately two 569 thousand systems. 571 A Master Browser SHOULD request all servers to register with it by 572 sending an AnnouncementRequest frame, if, on becoming the Master Browser 573 by winning an election, its server list is empty. Otherwise, clients 574 might get an incomplete list of servers until the servers' periodic 575 registrations fill the server list. 577 If the Master Browser on a subnet is not the Primary Domain Controller 578 (PDC), then it is a Local Master Browser. 580 A Local Master Browser MUST periodically synchronize with the Domain 581 Master Browser (which is the PDC). This synchronization is performed by 582 making a NetServerEnum2 request to the Domain Master Browser and merging 583 the results with its list of servers and domains. An entry from the 584 Domain Master Browser should be marked "non-local", and must not 585 overwrite an entry with the same name marked _authoritative_. The Domain 587 Master Browser is located as specified in Appendix B. 589 A Master Browser MUST participate in browser elections (see section 590 6.8). 592 A Master Browser for a domain "D" MUST, after winning an election, 594 register the NetBIOS unique name D(1d). 596 A Master Browser for a domain "D" MUST, after losing an election, 598 unregister the NetBIOS unique name D(1d), and do so quickly enough that 600 the winning browser can successfully register it. 602 A Master Browser MUST, if it receives a HostAnnouncement, 603 DomainAnnouncement, or LocalMasterAnnouncement frame another system that 604 claims to be the Master Browser for its domain, demote itself from 605 Master Browser and force an election. This ensures that there is only 606 ever one Master Browser in each workgroup or domain. 608 A Master Browser SHOULD, if it loses an election, become a Backup 609 Browser (without being told to do so by the new Master Browser). Since 610 it has more up-to-date information in its lists than a Potential 611 Browser, it is more efficient to have it be a Backup Browser than to 612 promote a Potential Browser. 614 4.4.3.1 Preferred Master Browser 616 A Preferred Master Browser supports exactly the same protocol elements 617 as a Potential Browser, except as follows. 619 A Preferred Master Browser MUST always force an election when it starts 620 up. 622 A Preferred Master Browser MUST participate in browser elections (see 623 section 6.8). 625 A Preferred Master Browser MUST set the Preferred Master bit in the 626 RequestElection frame (see section 6.7) to bias the election in its 628 favor. 630 A Preferred Master Browser SHOULD, if it loses an election, 631 automatically become a Backup Browser, without being told to do so by 632 the Master Browser. 634 4.4.4 Domain Master Browser 636 A Domain Master Browser for a domain MUST act as a Local Master Browser 638 for its subnet. Thus, it acts exactly like a Local Master Browser, 640 except where required to act differently by this section. 642 A Domain Master Browser MUST set type SV_TYPE_DOMAIN_MASTER (see section 644 6.4.1) in its HostAnnouncement until it is ready to shut down. In its 646 last HostAnnouncement frame before it shuts down, it SHOULD specify a 648 type of 0. 650 A Domain Master Browser for a domain MUST receive and process 652 MasterAnnouncement frames from Local Master Browsers of its domain, and 654 keep a list of all the Local Master Browsers in its domain. 656 A Domain Master Browser MUST periodically synchronize with the Local 658 Master Browsers for its domain. This synchronization is performed by 660 making a NetServerEnum2 request to each Local Master Browser for its 662 "authoritative" entries and merging the results into a master list for 664 the whole domain. 666 A Domain Master Browser MUST eventually purge an entry from its master 668 list if: 670 . it was originally received from a Local Master Browser 672 . it has not appeared in any list obtained from a Local Master Browser 674 for an implementation specific amount of time 676 . it has not received any MasterAnnouncement or HostAnnouncement for 678 the server or domain specified by the entry 680 A Domain Master Browser MUST set the PDC bit in the RequestElection 682 frame (see section 6.7) to bias the election in its favor. 684 A Domain Master Browser MAY be configured with a list of domains for 686 which it is to support cross-domain browsing. It MUST periodically 688 discover or validate the name of the Domain Master Browser for each such 690 domain using the mechanism in appendix B, and add this information to 692 its list of domains and their Domain Master Browsers. 694 5. Mailslot Protocol Specification 696 The only transaction allowed to a mailslot is a mailslot write. Mailslot 697 writes requests are encapsulated in CIFS TRANSACT SMBs and sent to a 699 specified NetBIOS name. The following table shows the interpretation of 701 the TRANSACT SMB parameters for a mailslot transaction: 703 Name Value Description 704 Command SMB_COM_TRANSACTION 705 Name STRING name of mail slot to write; 706 must start with "\MAILSLOT\" 707 SetupCount 3 Always 3 for mailslot writes 708 Setup[0] 1 Command code == write mailslot 709 Setup[1] Ignored 710 Setup[2] Ignored 711 TotalDataCount n Size of data in bytes to write to 712 the mailslot 713 Data[ n ] The data to write to the mailslot 715 When it is specified that a mailslot message is "sent to NetBIOS name X 717 and mailslot Y" it means that a NetBIOS datagram (as specified in 719 section 4.4.2 of [RFC 1002]) is sent whose 721 . MSG_TYPE is DIRECT_UNIQUE_DATAGRAM if the NetBIOS name is a unique 723 name 725 . MSG_TYPE is DIRECT_GROUP_DATAGRAM if the NetBIOS name is a group name 727 . SOURCE_NAME field is the NetBIOS name of the sending system 729 . DESTINATION_NAME is X 731 . USER_DATA field contains an SMB_COM_TRANSACTION SMB (as specified in 733 the CIFS spec) with its fields as specified in the table above. 735 (or the equivalent, if the NetBIOS service in use is over a protocol 737 other than as specified by RFC 1001/1002.) 739 In order to receive mailslot messages, a system MUST have done a NetBIOS 741 registration (as per section 5.2 of RFC 1001) of the DESTINATION_NAME to 743 which the message was sent. 745 Before sending a mailslot message, the sending system SHOULD have done a 747 NetBIOS registration of the SOURCE_NAME in the message to be sent. 749 6. Browser Protocol Specification 751 As already explained, browser datagrams are also referred to as Browser 752 frames. What distinguishes one browser frame from another is the opcode 754 that is carried as the data portion of the Transact SMB, and the NETBIOS 755 name and mailslot to which the browser frame is sent. Browser frames 757 are often referred to by the symbolic name of the opcode that is within 759 the data portion of the Transact SMB. The following sections describe 760 the various Browser frames. 762 6.1 NETBIOS Name Notation 764 NAME(xx) denotes the ASCII string "NAME," padded with spaces (0x20) to 765 15 bytes, with a hex xx value in the 16th byte. For example, the 766 notation FOOBAR(15) indicates a NETBIOS name consisting of the bytes: 767 [69,79,79,65,64,82,20,20,20,20,20,20,20,20,20, 15] 769 Names that are placeholders and that need to be substituted with their 770 actual values are bracketed within <>. Thus the string would 771 become _Redmond_ if the domain under consideration is named _Redmond_. 772 Details of the various NETBIOS names used for browsing are described in 773 Appendix C. 775 6.2 GetBackupListRequest Browser Frame 777 The GetBackupListRequest frame is sent by a browser client to any Master 778 Browser for a domain to allow the client to learn the identities of 779 Backup Browsers. To get the list of Backup Browsers for domain "D" from 781 the Local Master Browser for that domain, the GetBackupListRequest 783 browser frame is sent to to NETBIOS unique name D(1d) and mailslot 785 _\MAILSLOT\MSBROWSE_. To get the list of Backup Browsers for domain "D" 787 from the Domain Master Browser for that domain, the 789 GetBackupListRequest browser frame is sent to to NETBIOS unique name 791 D(1b) and mailslot _\MAILSLOT\MSBROWSE_. The definition of the 793 GetBackupListRequest frame is: 795 struct { 796 unsigned char OpCode; 797 unsigned short Token; 798 } 800 where : 802 OpCode identifies this structure as a request to return a list of Backup 803 servers. Opcode is defined as GetBackupListRequest and has a value of 804 decimal 9. 806 Token is a handle of meaning only to the client issuing the browser 807 frame. The Local Master Browser will return this token unmodified in the 808 response. The client should use this to distinguish replies to multiple 809 outstanding GetBackupList requests. This implies that every 810 GetBackupListRequest should have an unique handle, at least within the 811 outstanding lifetime of a request. 813 The expected response is a GetBackupListResponse frame (see next 814 section). 816 6.3 GetBackupListResponse Browser Frame 818 The GetBackupListResponse frame is sent by a Master Browser in response 819 to a GetBackupListRequest frame. The GetBackupListResponse frame is sent 821 to the NETBIOS unique name in the SOURCE_NAME of the mailslot message 823 containing the GetBackupListRequest and mailslot \MAILSLOT\LANMAN. Note: 825 this name is not part of the body of the request and on many systems the 827 Master Browser will need to obtain this name from the NetBIOS service. 829 The definition of the GetBackupListResponse frame is: 831 struct { 832 unsigned char OpCode; 833 unsigned short BackupServerCount; 834 unsigned short Token; 835 unsigned char BackupServerList[][] 836 } 837 where: 838 Opcode __Identifies this structure as a backup list. 840 BackupServerCount __Specifies the number of backup servers 841 that follow this list. 843 Token __Is returned unmodified to the client. This is used by 844 the client to associate an incoming BackupListResponse 845 with its BackupListRequest. 847 BackupServerList __ASCII backup servers. Each server name is 848 null terminated and up to 16 bytes in length. 850 6.4 The NetServerEnum2 RAP Service 852 The NetServerEnum2 RAP service lists all computers of the specified type 853 or types that are visible in the specified domains. It may also 854 enumerate domains. 856 The following definition uses the notation and terminology defined in 857 the CIFS Remote Administration Protocol specification, which is required 858 in order to make it well-defined. The definition is: 860 unsigned short NetServerEnum2 ( 861 unsigned short sLevel, 862 RCVBUF pbBuffer, 863 RCVBUFLEN cbBuffer, 864 ENTCOUNT pcEntriesRead, 865 unsigned short *pcTotalAvail, 866 unsigned long fServerType, 867 char *pszDomain, 868 ); 870 where: 872 sLevel specifies the level of detail (0 or 1) requested. 874 pbBuffer points to the buffer to receive the returned data. If the 875 function is successful, the buffer contains a sequence of 876 server_info_x structures, where x is 0 or 1, depending on the 877 level of detail requested. 879 cbBuffer specifies the size, in bytes, of the buffer pointed to by 880 the pbBuffer parameter. 882 pcEntriesRead points to a 16 bit variable that receives a count of 883 the number of servers enumerated in the buffer. This count is 884 valid only if NetServerEnum2 returns the NERR_Success or 885 ERROR_MORE_DATA values. 887 pcTotal Avail points to a 16 bit variable that receives a count of 888 the total number of available entries. This count is valid only if 889 NetServerEnum2 returns the NERR_Success or ERROR_MORE_DATA values. 891 fServerType specifies the type or types of computers to enumerate. 892 Computers that match at least one of the specified types are 893 returned in the buffer. Possible values are defined in the request 894 parameters section. 896 pszDomain points to a null-terminated string that contains the 897 name of the workgroup in which to enumerate computers of the 898 specified type or types. If the pszDomain parameter is a null 899 string or a null pointer, servers are enumerated for the current 900 domain of the computer. 902 6.4.1 Transaction Request Parameters section 904 The Transaction request parameters section in this instance contains: 905 . The 16 bit function number for NetServerEnum2 which is 104. 906 . The parameter descriptor string which is "WrLehDz". 907 . The data descriptor string for the (returned) data which is "B16" for 908 level detail 0 or "B16BBDz" for level detail 1. 909 . The actual parameters as described by the parameter descriptor 910 string. 912 The parameters are: 914 . A 16 bit integer with a value of 0 or 1 (corresponding to the "W" in 915 the parameter descriptor string. This represents the level of detail 916 the server is expected to return 917 . A 16 bit integer that contains the size of the receive buffer. 918 . A 32 bit integer that represents the type of servers the function 919 should enumerate. The possible values may be any of the following or 920 a combination of the following: 922 SV_TYPE_WORKSTATION 0x00000001 All workstations 923 SV_TYPE_SERVER 0x00000002 All servers 924 SV_TYPE_SQLSERVER 0x00000004 Any server running with SQL 925 server 926 SV_TYPE_DOMAIN_CTRL 0x00000008 Primary domain controller 927 SV_TYPE_DOMAIN_BAKCTRL 0x00000010 Backup domain controller 928 SV_TYPE_TIME_SOURCE 0x00000020 Server running the timesource 929 service 930 SV_TYPE_AFP 0x00000040 Apple File Protocol servers 931 SV_TYPE_NOVELL 0x00000080 Novell servers 932 SV_TYPE_DOMAIN_MEMBER 0x00000100 Domain Member 933 SV_TYPE_PRINTQ_SERVER 0x00000200 Server sharing print queue 934 SV_TYPE_DIALIN_SERVER 0x00000400 Server running dialin service. 935 SV_TYPE_XENIX_SERVER 0x00000800 Xenix server 936 SV_TYPE_NT 0x00001000 NT server 937 SV_TYPE_WFW 0x00002000 Server running Windows for 938 Workgroups 939 SV_TYPE_SERVER_NT 0x00008000 Windows NT non DC server 940 SV_TYPE_POTENTIAL_BROWSER 0x00010000 Server that can run the browser 941 service 942 SV_TYPE_BACKUP_BROWSER 0x00020000 Backup browser server 943 SV_TYPE_MASTER_BROWSER 0x00040000 Master browser server 944 SV_TYPE_DOMAIN_MASTER 0x00080000 Domain Master Browser server 945 SV_TYPE_LOCAL_LIST_ONLY 0x40000000 Enumerate only 947 entries marked "local"local 949 entries (marked 951 "authoritative"). This is 953 meaningful only for the 955 NetServerEnum2 request and 957 should be ignored within the 959 NetServerEnum2 response. 961 SV_TYPE_DOMAIN_ENUM 0x80000000 Enumerate Domains. The pszDomain 962 parameter must be NULL. 964 . A null terminated ASCII string representing the pszDomain parameter 965 described above 966 6.4.2 Transaction Request Data section 968 There is no data or auxiliary data to send as part of the request. 970 6.4.3 Transaction Response Parameters section 972 The transaction response parameters section consists of: 973 . A 16 bit word indicating the return status. The possible values are: 975 Code Value Description 976 NERR_Success 0 No errors encountered 977 ERROR_MORE_DATA 234 Additional data is available 978 NERR_ServerNotStarted 2114 The RAP service on the remote computer 979 is not running 980 NERR_BadTransactConfig 2141 The server is not configured for 981 transactions, IPC$ is not shared 983 . A 16 bit "converter" word. 984 . A 16 bit number representing the number of entries returned. 985 . A 16 bit number representing the total number of available entries. 986 If the supplied buffer is large enough, this will equal the number of 987 entries returned. 989 6.4.4 Transaction Response Data section 991 The return data section consists of a number of SHARE_INFO_1 structures. 992 The number of such structures present is determined by the third entry 993 (described above) in the return parameters section. 995 At level detail 0, the Transaction response data section contains a 996 number of SERVER_INFO_0 data structure. The number of such structures is 997 equal to the 16 bit number returned by the server in the third parameter 998 in the Transaction response parameter section. The SERVER_INFO_0 data 999 structure is defined as: 1001 struct SERVER_INFO_0 { 1002 char sv0_name[16]; 1003 }; 1005 where: 1007 sv0_name is a null-terminated string that specifies the name of a 1008 computer or domain . 1010 At level detail 1, the Transaction response data section contains a 1011 number of SERVER_INFO_1 data structure. The number of such structures is 1012 equal to the 16 bit number returned by the server in the third parameter 1013 in the Transaction response parameter section. The SERVER_INFO_1 data 1014 structure is defined as: 1016 struct SERVER_INFO_1 { 1017 char sv1_name[16]; 1018 char sv1_version_major; 1019 char sv1_version_minor; 1020 unsigned long sv1_type; 1021 char *sv1_comment_or_master_browser; 1022 }; 1024 sv1_name contains a null-terminated string that specifies the name 1025 of a computer, or a domain name if SV_TYPE_DOMAIN_ENUM is set in 1026 sv1_type. 1028 sv1_version_major whatever was specified in the HostAnnouncement 1029 or DomainAnnouncement frame with which the entry was registered. 1031 sv1_version_minor whatever was specified in the HostAnnouncement 1032 or DomainAnnouncement frame with which the entry was registered. 1034 sv1_type specifies the type of software the computer is running. 1035 The member can be one or a combination of the values defined above 1036 in the Transaction request parameters section for fServerType. 1038 sv1_comment_or_master_browser points to a null-terminated string. If 1039 the sv1_type indicates that the entry is for a domain, this 1040 specifies the name of server running the domain master browser; 1041 otherwise, it specifies a comment describing the server. The comment 1042 can be a null string or the pointer may be a null pointer. 1044 In case there are multiple SERVER_INFO_1 data structures to 1045 return, the server may put all these fixed length structures in 1046 the return buffer, leave some space and then put all the variable 1047 length data (the actual value of the sv1_comment strings) at the 1048 end of the buffer. 1050 There is no auxiliary data to receive. 1052 6.5 HostAnnouncement Browser Frame 1054 To advertise its presence, i.e. to publish itself as being available, a 1055 non-browser server sends a HostAnnouncement browser frame. If the server 1056 is a member of domain "D", this frame is sent to the NETBIOS unique name 1057 D(1d) and mailslot _\MAILSLOT\MSBROWSE_. The definition of the 1058 HostAnnouncement frame is: 1060 struct { 1061 unsigned char Opcode; 1062 unsigned char UpdateCount; 1063 unsigned long Periodicity; 1064 unsigned char ServerName[]; 1065 unsigned char VersionMajor; 1066 unsigned char VersionMinor; 1067 unsigned long Type; 1068 unsigned long Signature; 1069 unsigned char Comment[]; 1070 } 1072 where: 1073 Opcode __Identifies this structure as a browser server 1074 announcement and is defined as HostAnnouncement with a 1075 value of decimal 1. 1077 UpdateCount _ must be sent as zero and ignored on receipt. 1079 Periodicity __The announcement frequency of the server (in 1080 milliseconds). The server will be removed from the browse 1082 list if it has not been heard from in 3X its announcement 1083 frequency. In no case will the server be removed from the 1084 browse list before the period 3X has elapsed. Actual 1085 implementations may take more than 3X to actually remove 1086 the server from the browse list. 1088 ServerName __Null terminated ASCII server name (up to 16 bytes 1089 in length). This name SHOULD be registered with NetBIOS by 1091 the server offering the services specified in the Type 1093 field. 1095 VersionMajor __The major version number of the OS the server 1096 is running. it will be returned by NetServerEnum2. 1098 VersionMinor __The minor version number of the OS the server 1099 is running. This is entirely informational and does not 1100 have any significance for the browsing protocol. 1102 Type __Specifies the type of the server. The server type bits 1103 are specified in the NetServerEnum2 section. 1105 Signature __ The browser protocol minor version number in the 1106 low 8 bits, the browser protocol major version number in 1107 the next higher 8 bits and the signature 0xaa55 in the 1108 high 16 bits of this field. Thus, for this version of the 1109 browser protocol (1.15) this field has the value 1110 0xaa55010f. This may used to isolate browser servers that 1111 are running out of revision browser software; otherwise, 1112 it is ignored. 1114 Comment __Null terminated ASCII comment for the server. 1115 Limited to 43 bytes. 1117 When a non-browser server starts up, it announces itself in the manner 1118 described once every minute. The frequency of these statements is 1119 gradually stretched to once every 12 minutes. 1121 Note: older non-browser servers in a domain "D" sent HostAnnouncement 1122 frames to the NETBIOS group name D(00). Non-Browser servers supporting 1123 version 1.15 of the browsing protocol SHOULD NOT use this NETBIOS name, 1124 but for backwards compatibility Master Browsers MAY receive and process 1125 HostAnnouncement frames on this name as described above for D(1d). 1127 6.6 AnnouncementRequest Browser Frame 1129 When a Master Browser starts up and its browse list is empty, it may 1130 force all servers to announce themselves by broadcasting an 1131 AnnouncementRequest frame. If the Master Browser serves domain "D", the 1132 AnnouncementRequest frame is broadcast using the NETBIOS group name 1133 D(00) and mailslot _\MAILSLOT\LANMAN_. The definition of the 1134 AnnouncementRequest frame is: 1136 struct { 1137 unsigned char Opcode; 1138 unsigned char ResponseComputerName[]; 1139 }; 1141 Opcode __Identifies this structure as an announcement request 1142 and is defined as AnnounceMent Request with a value of 1143 decimal 2. 1145 ResponseComputerName __Specifies the name of the computer to 1146 send the server announcement to and is up to 16 bytes in 1147 length. This is ignored . The response to this browser 1148 frame is a HostAnnouncement browser frame as described 1149 immediately above. That browser frame does not use this 1150 parameter at all. 1152 Recipients of this packet should reply by sending an HostAnnouncement 1153 frame as described above. The reply should be sent within a randomly 1154 determined time period that may have a duration of up to 30 seconds. The 1155 random delay ensures that the Master Browser who sent out the packet 1156 does not get flooded with replies, all at the same time. 1158 6.7 RequestElection Browser Frame 1160 To force the election of a new Master Browser for a domain, any browser 1161 client or server can broadcast a RequestElection frame. If the election 1162 is for domain "D", the frame is broadcast using the NETBIOS group name 1163 D(1e) and mailslot _\MAILSLOT\MSBROWSE_. The definition of the 1164 RequestElection frame is: 1166 struct { 1167 unsigned char Opcode; 1168 unsigned char Version; 1169 unsigned long Criteria; 1170 unsigned long TimeUp; 1171 unsigned long MustBeZero; 1172 unsigned char ServerName[]; 1173 } 1175 Opcode __Identifies this structure as an election request, and is 1176 defined as RequestElection, with a value of decimal 8. 1178 Version __Specifies the version of this election packet. This is a 1179 constant and always has the value 0x00010f00 1181 Criteria __Specifies the election criteria of the sender. Produced 1182 by OR'ing together the Version and the following: 1184 OS info: 1185 Windows for Workgroups & Windows 95: 0x00000000 1186 Windows NT: 0x01000000 1187 Windows NT Server: 0x02000000 1188 Role: 1189 PDC: 0x00000080 1190 Preferred Master: 0x00000008 1191 Running Master: 0x00000004 1192 Backup Browser which was 1193 recently a Master Browser: 0x00000002 1194 Running Backup Browser: 0x00000001 1195 Using NBNS for NETBIOS: 0x00000020 1197 The following masks can be used to isolate parts of the Criteria: 1199 Operating System Type Mask 0xFF000000 1200 Election Protocol Version Mask: 0x00FFFF00 1201 Per version criteria mask: 0x000000FF 1203 TimeUp __The number of seconds that the server has been up. 1205 MustBeZero__Must be zero. 1207 ServerName __Null terminated ASCII server name (up to 16 bytes in 1208 length). 1210 6.8 Browser Elections 1212 All browsers for a domain "D" MUST listen for RequestElection frames on 1213 the group name D(1e) and mailslot _\MAILSLOT\MSBROWSE_. 1215 Elections proceed in rounds. A round is initiated when a RequestElection 1216 frame is sent. When a Browser receives a RequestElection frame, it 1217 determines if it has won the round using the following rules: 1219 If it has lost an election in the last several seconds, it loses 1220 If its election Version is greater than the senders election 1221 Version, it wins 1222 Else if its election Criteria (including the election version) 1223 is greater than the senders Criteria, it wins 1224 Else if it has been up longer than the sender, it wins 1225 Else if its name is lexically lower than the sender's name, it 1226 wins 1227 (I.e., at this point, a sever named A will become Master 1228 Browser over a server named X) 1230 (Note that many browsers which receive a RequestElection frame may win a 1231 round.) 1233 Each time it wins a round, a browser sends out a RequestElection frame, 1234 after a delay based on the browser's current role in the domain: 1235 . Master Browsers and Domain Master Browsers delay for 100 ms. 1236 . Backup Browsers delay for an amount randomly chosen from the interval 1237 200-600 ms. 1238 . All other browsers delay for an amount randomly chosen from the 1239 interval 800-3000 ms. 1241 If a browser loses a round it drops out of the election by ignoring 1242 RequestElection frames until it receives a LocalMasterAnnouncement frame 1243 that tells which system is the new Master Browser. 1245 If a browser wins 4 rounds in a row, it becomes the Master Browser. 1247 6.9 BecomeBackup Browser Frame 1249 If a Local Master Browser for a domain "D" wants to promote a Potential 1250 Browser to Backup Browser, it broadcasts a BecomeBackup frame using the 1251 NETBIOS group name D(1e) and the _\MAILSLOT\MSBROWSE_ mailslot. The 1252 definition of the BecomeBackup frame is: 1254 struct { 1255 unsigned char Opcode; 1256 unsigned char BrowserToPromote[]; 1257 } 1259 Opcode __ Identifies this structure as a browser server 1260 announcement, is defined as BecomeBackup, with a value of 1261 decimal 11 1263 BrowserToPromote __Specifies the name of the browser server to 1264 be promoted to backup. Maximum of 16 bytes in length. 1266 6.10 LocalMasterAnnouncement Browser Frame 1268 A Local Master Browser for a domain announces itself to all the other 1269 browsers in its domain that are on its subnet using the 1270 LocalMasterAnnouncement frame. If the Local Master Browser serves domain 1271 "D", the LocalMasterAnnouncement frame is broadcast using the NETBIOS 1272 group name D(1e) and the mailslot _\MAILSLOT\MSBROWSE_. The definition 1273 of the LocalMasterAnnouncement frame is: 1275 struct { 1276 unsigned char Opcode; 1277 unsigned char UpdateCount; 1278 unsigned long Periodicity; 1279 unsigned char ServerName[]; 1280 unsigned char VersionMajor; 1281 unsigned char VersionMinor; 1282 unsigned long Type; 1283 unsigned long Signature; 1284 unsigned char Comment[]; 1285 } 1287 where: 1288 Opcode __Identifies this structure as a browser server 1289 announcement and is defined as LocalMasterAnnouncement 1290 with a value of decimal 15. 1292 UpdateCount _ must be sent as zero and ignored on receipt. 1294 Periodicity __The announcement frequency of the browser (in 1295 milliseconds). The browser will be removed from the browse 1297 list if it has not been heard from in 3X its announcement 1298 frequency. In no case will the server be removed from the 1299 browse list before the period 3X has elapsed. Actual 1300 implementations may take more than 3X to remove the server 1301 from the browse list. 1303 ServerName __Null terminated ASCII server name (up to 16 bytes 1304 in length). 1306 VersionMajor __The major version of the OS the server is 1307 running. This value is informational and irrelevant to the 1308 browsing protocol. 1310 VersionMinor __The minor version of the OS the server is 1311 running. This value is informational and irrelevant to the 1312 browsing protocol. 1314 Type __Specifies the type of the browser. The type bits are 1315 specified in the description of NetServerEnum2. 1317 Signature __ The browser protocol minor version number in the 1318 low 8 bits, the browser protocol major version number in 1319 the next higher 8 bits and the signature 0xaa55 in the 1320 high 16 bits of this field. This may used to isolate 1321 browser servers that are running out of revision browser 1322 software; otherwise, it is ignored. Thus, for this version 1323 of the browser protocol (1.15) this field has the value 1324 0xaa55010f. 1326 Comment __Null terminated ASCII comment for the browser. 1327 Limited to 43 bytes. 1329 Local Master Browsers do not need to send HostAnnouncement frames; the 1330 LocalMasterAnnouncement accomplishes that function. 1332 6.11 MasterAnnouncement browser Frame 1334 The MasterAnnouncement frame is sent by a Local Master Browser to the 1335 Domain Master Browser, which runs on the PDC. If the name of the PDC is 1336 "PDCName", then the MasterAnnouncement frame is sent to the NETBIOS 1337 unique name PDCName(00) and mailslot _\MAILSLOT\MSBROWSE_. Appendix B 1338 describes how to determine the name of the Primary Domain Controller. 1339 The definition of the MasterAnnouncement frame is:: 1341 struct { 1342 unsigned char Opcode; 1343 unsigned char MasterBrowserServerName[]; 1344 }; 1346 Opcode __Identifies this structure as a master browser server 1347 announcement and is defined as MasterAnnouncement with a value 1348 of decimal 13. 1350 MasterBrowserServerName __Specifies the name of the master browser 1351 server (up to 16 bytes in length). 1353 6.12 DomainAnnouncement Browser Frame 1355 Master Browsers (including Local Master Browsers and Domain Master 1356 Browsers) announce the domain they serve to any other Master Browsers on 1357 their subnet by broadcasting a DomainAnnouncement frame using the 1358 NETBIOS group name _(01)(02)__MSBROWSE__(02)(01)_ and mailslot 1360 _\MAILSLOT\MSBROWSE_. The definition of the DomainAnnouncement frame is: 1362 struct { 1363 unsigned char Opcode; 1364 unsigned char UpdateCount; 1365 unsigned long Periodicity; 1366 unsigned char DomainName[]; 1367 unsigned char VersionMajor; 1368 unsigned char VersionMinor; 1369 unsigned long Type; 1370 unsigned long Signature; 1371 unsigned char MasterBrowserName[]; 1372 } 1374 where: 1375 Opcode __Identifies this structure as a browser server 1376 announcement and is defined as DomainAnnouncement with a 1377 value of decimal 12. 1379 UpdateCount _ must be sent as zero and ignored on receipt. 1381 Periodicity __The announcement frequency of the domain (in 1382 milliseconds). The domain will be removed from the browse 1384 list if it has not been heard from in 3X its announcement 1385 frequency. In no case will the domain be removed from the 1386 browse list before the period 3X has elapsed. Actual 1387 implementations may take more than 3X to actually remove 1388 the domain from the browse list. 1390 DomainName __Null terminated ASCII server name (up to 16 bytes 1391 in length). 1393 VersionMajor __The major version of the OS the server is 1394 running. This value is informational and irrelevant to the 1395 browsing protocol. 1397 VersionMinor __The minor version of the OS the server is 1398 running. This value is informational and irrelevant to the 1399 browsing protocol. 1401 Type __Specifies the type of the server. The server type bits 1402 are specified in the previous section. 1404 Signature __ The browser protocol minor version number in the 1405 low 8 bits, the browser protocol major version number in 1406 the next higher 8 bits and the signature 0xaa55 in the 1407 high 16 bits of this field. This may used to isolate 1408 browser servers that are running out of revision browser 1409 software; otherwise, it is ignored. Thus, for this version 1410 of the browser protocol (1.15) this field has the value 1411 0xaa55010f. 1413 MasterBrowserName __Null terminated ASCII string containing 1414 the name of the master browser server for this domain. 1416 7. References 1417 [CIFS 96} I. Heizer, P. Leach, D. Perry, "Common Internet Files 1418 System Protocol (CIFS/1.0)", Internet-Draft, ,June 30, 1996 . (Work in Progress) 1420 [RFC 1001] K. Auerbach, A. Aggarwal, "Protocol Standard for a 1421 NETBIOS Service on a TCP/UDP Transport: Concepts and Methods", 1422 RFC 1001, Epilogue Technology, March 1987. 1423 [Bradner 96] S. Bradner, ""Key words for use in RFCs to Indicate 1424 Requirement Levels", Internet-Draft, , August 1996 (Work in Progress) 1427 8. Author's Addresses 1428 Paul Leach 1429 Dilip Naik 1430 Microsoft 1431 1 Microsoft Way 1432 Redmond, WA 98052 1433 paulle@microsoft.com 1434 v-dilipn@microsoft.com 1436 9. Appendix A - Multi-net considerations 1438 To begin with, let's clearly define what is meant by multiple networks 1439 here. A computer can be running one or more network protocols on a 1440 single network adapter card such as IP and IPX. Each of these is 1441 considered to be a _network_ for the purposes of this paragraph. A 1442 computer could also have multiple network adapter cards, and there could 1443 be different protocols running on the different adapter cards, or even 1444 the same protocol(s) on all of the adapter cards. So, more precisely, a 1445 network here means a transport protocol per adapter card. A computer 1446 with 2 physical network cards, running 2 different transport protocols 1447 on each network card, would have 4 logical networks. 1449 Browsers need to remember which logical network a server is located on. 1450 When a client queries a browser for a list of servers, the browser 1451 server needs to return a list of servers that are on the same logical 1452 network on which the client query arrived at the browser server. So a 1453 client that sends a browser frame using say IP will only be returned 1454 information about servers that sent announcements using IP. 1455 To summarize, browser servers need to understand the concept of logical 1456 networks and track server announcements as well as client queries on a 1457 per logical network basis. 1459 10. Appendix B - Primary Domain Controller Location Protocol 1461 This appendix details how a client goes about locating a Primary Domain 1462 Controller (PDC). The process is rather involved, because different 1463 versions of the PDC have used different versions of the protocol, and 1464 hence a client that does not know what protocol is supported by its PDC 1465 has to try them all. 1467 A Primary Domain Controller (PDC) for a domain "D" is located by sending 1468 a mailslot message containing a NETLOGON_QUERY frame to a NETBIOS name 1469 and mailslot "\NET\NETLOGON" and then waiting for a reply mailslot 1470 message, which will be sent to the mailslot name specified by the client 1471 in the NETLOGON_QUERY structure., and which will contain a 1472 NETLOGON_RESPONSE structure. If there is no response after a delay, the 1473 message may be retransmitted. The delay MUST be at least twice the 1474 expected service time, and the delay should be doubled after each time- 1475 out. 1477 If a reply is received, the name of the PDC SHOULD be cached for future 1478 use, so as time minimize network traffic. If no reply is received after 1479 several retransmissions, the PDC may be declared to be unreachable, and 1480 no further attempt to locate it should be made for a while (exactly how 1481 long depends on the expected recovery time for a PDC and/or for the 1482 network; typically a minute or so, but should be increased after each 1483 failure). 1485 The only difference between versions of the protocol is the NETBIOS name 1486 to which the message is sent, as follows: 1488 NETBIOS name PDC's OS version 1489 name type ============= 1490 =========== ======== 1491 D(1b) unique Windows NT 3.51 or later or compatible 1492 D(1c) group Windows NT 3.1 or later or compatible 1493 D(00) group all 1495 Clients which are configured to know or are willing to assume what 1496 version of the protocol their PDC is running may directly use the 1497 appropriate NETBIOS name for that version. Otherwise, they SHOULD first 1498 attempt D(1b), since it is unicast and creates the least network 1499 traffic; if there is no response, then they SHOULD try the others. They 1500 MAY try them in parallel. 1502 The NETLOGON_QUERY structure is defined as : 1504 struct NETLOGON_QUERY{ 1505 unsigned char Opcode; 1506 char ComputerName[]; 1507 char MailslotName[]; 1508 unsigned short Lm20Token; 1509 } ; 1511 Opcode __Identifies this structure as a NETLOGON_QUERY and has a 1512 value of 0x07. 1514 ComputerName __Specifies the ASCII name of the computer sending the 1515 query, and is up to 16 bytes in length. The response is sent to 1516 NETBIOS unique name (00). 1518 MailslotName __Specifies the ASCII name of the mailslot to which the 1519 response is to be sent, and is up to 256 bytes in length; cannot 1520 be _\MAILSLOT\LANMAN_ or _\MAILSLOT\MSBROWSE_ or 1521 "\NET\NETLOGON". 1523 Lm20Token - has a value of 0xFFFF. 1525 The response mailslot message contains a NETLOGON_RESPONSE data 1526 structure that is defined as the following for non Windows NT clients: 1528 struct NETLOGON_RESPONSE 1529 { 1530 unsigned char Opcode; 1531 char PrimaryDCName[16]; 1532 unsigned short Lm20Token; 1533 }; 1535 where 1536 Opcode __Identifies this structure as a NETLOGON_RESPONSE and has a 1537 value of 0x12. 1539 PrimaryDCName __Specifies the ASCII name of the Primary Domain 1540 Controller and is up to 16 bytes in length. 1542 Lm20Token - has a value of 0xFFFF 1544 Note that this procedure to locate a Primary Domain Controller is 1545 expensive in terms of network traffic. The Microsoft implementations 1546 attempt to alleviate this by caching the PDC Name. Before using the 1547 cached PDC Name, a NetServerEnum2 API is remoted to the PDC and a sanity 1548 check is performed to ensure that the server type returned indicates a 1549 Primary Domain Controller 1551 11. Appendix C - Summary of Special NETBIOS Names 1553 This section details the various NETBIOS names that are involved in 1554 sending and receiving browser frames. The different mailslots involved 1555 in browsing (there are only 3) are described later on when the browser 1556 frames are detailed. 1558 11.1 Registered unique names 1560 (00) 1561 This name is used by all servers and clients to receive second 1562 class mailslot messages. A system must add this name in order to 1563 receive mailslot messages. The only browser requests that should 1564 appear on this name are BecomeBackup, GetBackupListResp, 1565 MasterAnnouncement, and LocalMasterAnnouncement frames. All other 1566 datagrams (other than the expected non-browser datagrams) may be 1567 ignored and an error logged. 1569 (1d) 1570 This name is used to identify a master browser server for domain 1571 "DOMAIN" on a subnet. A master browser server adds this name as a 1572 unique NETBIOS name when it becomes master browser. If the attempt 1573 to add the name fails, the master browser server assumes that there 1574 is another master in the domain and will fail to come up. It may 1575 log an error if the failure occurs more than 3 times in a row (this 1576 either indicates some form of network misconfiguration or a 1577 software error). The only requests that should appear on this name 1578 are GetBackupListRequest and HostAnnouncement requests. All other 1579 datagrams on this name may be ignored (and an error logged). If 1580 running a NETBIOS name service (NBNS, such as WINS), this name 1581 should not be registered with the NBNS. 1583 (1b) 1584 This name is used to identify the Domain Master Browser for domain 1585 "DOMAIN" (which is also the primary domain controller). It is a 1586 unique name added only by the primary domain controller. The 1587 primary domain controller will respond to GetBackupListRequest on 1588 this name just as it responds to these requests on the (1d) 1589 name. 1591 11.2 Registered group names 1593 (01)(02)__MSBROWSE__(02)(01) 1594 This name is used by Master Browsers to announce themselves to the 1595 other Master Browsers on a subnet. It is added as a group name by 1596 all Master Browser servers. The only broadcasts that should appear 1597 on this name is DomainAnnouncement requests. All other datagrams 1598 can be ignored. 1600 (00) 1601 This name is used by clients and servers in domain "DOMAIN" to 1602 process server announcements. The only requests that should appear 1603 on this name that the browser is interested in are 1604 AnnouncementRequest and NETLOGON_QUERY (to locate the PDC) packets. 1605 All other unidentifiable requests may be ignored (and an error 1606 logged). 1608 (1e) 1609 This name is used for announcements to browsers for domain "DOMAIN" 1610 on a subnet. This name is registered by all the browser servers in 1611 the domain. The only requests that should appear on this name are 1612 RequestElection and AnnouncementRequest packets. All other 1613 datagrams may be ignored (and an error logged). 1615 (1c) 1616 This name is registered by Primary Domain Controllers. 1618 12. Appendix D - Browsing Protocol Evolution 1620 This Appendix details how the Microsoft Browser specification evolved 1621 and correlates the evolution to specific Microsoft products. 1623 The first browser implementation was with Lan Manager 1.0. Here, there 1624 were no browser servers as such. Each client acted as its own browser 1625 server. All servers announced themselves by means of datagrams and every 1626 client and server listened for those datagrams. Obviously, the amount of 1627 browser datagram traffic is fairly high and scales extremely poorly with 1628 an increase in the number of servers. 1630 The next major revision in the browser specification was with Windows 1631 For Workgroups. This is where the concept of a browser server was really 1632 introduced. 1634 Windows NT 3.51 expanded upon what Windows For Workgroups built. Windows 1635 NT 3.51 introduced the special NETBIOS name (1b) that is 1636 registered with WINS. Windows NT 3.51 also shipped a new redirector for 1637 Windows For Workgroups that could take advantage of this new 1638 (1b) name. 1640 In a domain which spans multiple broadcast areas, it may be necessary to 1641 have a configuration file available that can resolve the address of a 1642 browser server. This is because browsers rely on broadcasts for name 1643 resolution, for historical reasons. But these name resolution broadcast 1644 packets are not forwarded by routers that span the multiple broadcast 1645 areas of a domain. One example of such a configuration file is the 1646 LMHOSTS file on Windows NT machines.