home *** CD-ROM | disk | FTP | other *** search
/ ftp.microsoft.com / 2002-07-02_ftp.microsoft.com.zip / developr / drg / CIFS / cifsbrow.txt < prev    next >
Text File  |  1997-01-29  |  75KB  |  2,075 lines
  1.  
  2.  
  3.  
  4.  
  5.  
  6.  
  7. Network Working Group                    Paul J. Leach, Microsoft
  8. INTERNET-DRAFT                           Dilip C. Naik, Microsoft
  9. draft-leach-cifs-browser-spec-00.txt
  10. Category: Informational
  11. Expires June 10, 1997                            January 10, 1997
  12.  
  13.  
  14.  
  15.                         CIFS/E Browser Protocol
  16.                            Preliminary Draft
  17.  
  18.  
  19.  
  20.  
  21. STATUS OF THIS MEMO
  22.  
  23. THIS IS A PRELIMINARY DRAFT OF AN INTERNET-DRAFT. IT DOES NOT REPRESENT
  24. THE CONSENSUS OF ANY WORKING GROUP.
  25.  
  26. This document is an Internet-Draft. Internet-Drafts are working
  27. documents of the Internet Engineering Task Force (IETF), its areas, and
  28. its working groups. Note that other groups may also distribute working
  29. documents as Internet-Drafts.
  30.  
  31. Internet-Drafts are draft documents valid for a maximum of six months
  32. and may be updated, replaced, or obsoleted by other documents at any
  33. time. It is inappropriate to use Internet-Drafts as reference material
  34. or to cite them other than as "work in progress".
  35.  
  36. To learn the current status of any Internet-Draft, please check the
  37. "1id-abstracts.txt" listing contained in the Internet-Drafts Shadow
  38. Directories on ftp.is.co.za (Africa), nic.nordu.net (Europe),
  39. munnari.oz.au (Pacific Rim), ds.internic.net (US East Coast), or
  40. ftp.isi.edu (US West Coast).
  41.  
  42. Distribution of this document is unlimited. Please send comments to the
  43. authors or the CIFS mailing list at <cifs@listserv.msn.com>. Discussions
  44. of the mailing list are archived at
  45. <URL:http://microsoft.ease.lsoft.com/archives/cifs.html>.
  46.  
  47. ABSTRACT
  48.  
  49. The CIFS/E (CIFS extensions for enterprise networks) family of protocols
  50. includes a protocol for browsing. Browsing is a mechanism for
  51. discovering servers that are running particular services (not just CIFS
  52. file services). Servers are organized into named groups called domains,
  53. which form browsing scopes. This document specifies version 1.15 of  the
  54. browsing protocol. It also specifies the mailslot protocol, because the
  55. browsing protocol depends on it (and  is the only CIFS/E protocol which
  56. does).
  57.  
  58.  
  59.  
  60.  
  61.  
  62. Leach, Naik                                              [Page 1]
  63.  
  64.  
  65. INTERNET-DRAFT    CIFS/E Browser Protocol        January 10, 1997
  66.  
  67.  
  68. Table of Contents
  69.  
  70.  
  71. 1. INTRODUCTION........................................................3
  72.  
  73.  
  74.  
  75. 2. PREREQUISITES.......................................................3
  76.  
  77.  
  78.  
  79. 3. BROWSER OVERVIEW....................................................3
  80.  
  81.  
  82.  
  83. 4. BROWSING PROTOCOL ARCHITECTURE......................................5
  84.  
  85.  
  86.  4.1 LAYERING OF BROWSING PROTOCOL REQUESTS ...........................5
  87.  
  88.  4.2 BROWSER CLIENT ...................................................7
  89.  
  90.  4.3 NON-BROWSER SERVER ...............................................8
  91.  
  92.  4.4 BROWSER SERVERS ..................................................9
  93.  
  94.   4.4.1 Potential Browser Server ......................................9
  95.  
  96.   4.4.2 Backup Browser ................................................9
  97.  
  98.   4.4.3 Master Browser ...............................................10
  99.  
  100.   4.4.4 Domain Master Browser ........................................13
  101.  
  102.  
  103. 5. MAILSLOT PROTOCOL SPECIFICATION....................................13
  104.  
  105.  
  106.  
  107. 6. BROWSER PROTOCOL SPECIFICATION.....................................15
  108.  
  109.  
  110.  6.1 NETBIOS NAME NOTATION ...........................................15
  111.  
  112.  6.2 GETB     L         ACKUP ISTREQUEST BROWSER FRAME ..............................16
  113.  
  114.  6.3 GETBACKUPLISTRESPONSE BROWSER FRAME .............................16
  115.  
  116.  6.4 THE NETSERVERENUM2 RAP SERVICE ..................................17
  117.  
  118.   6.4.1 Transaction Request Parameters section .......................18
  119.  
  120.   6.4.2 Transaction Request Data section .............................19
  121.  
  122.  
  123. Leach, Naik                                              [Page 2]
  124.  
  125.  
  126. INTERNET-DRAFT    CIFS/E Browser Protocol        January 10, 1997
  127.  
  128.  
  129.   6.4.3 Transaction Response Parameters section ......................19
  130.  
  131.   6.4.4 Transaction Response Data section ............................20
  132.  
  133.  6.5 HOSTANNOUNCEMENT BROWSER FRAME ..................................21
  134.  
  135.  6.6 ANNOUNCEMENTREQUEST BROWSER FRAME ...............................22
  136.  
  137.  6.7 REQUESTELECTION BROWSER FRAME ...................................23
  138.  
  139.  6.8 BROWSER ELECTIONS ...............................................24
  140.  
  141.  6.9 BECOMEBACKUP BROWSER FRAME ......................................25
  142.  
  143.  6.10 LOCALMASTERANNOUNCEMENT BROWSER FRAME ..........................25
  144.  
  145.  6.11 MASTERANNOUNCEMENT BROWSER FRAME ...............................27
  146.  
  147.  6.12 DOMAINANNOUNCEMENT BROWSER FRAME ...............................27
  148.  
  149.  
  150. 7. REFERENCES.........................................................28
  151.  
  152.  
  153.  
  154. 8. AUTHOR'S ADDRESSES.................................................28
  155.  
  156.  
  157.  
  158. 9. APPENDIX A - MULTI-NET CONSIDERATIONS..............................29
  159.  
  160.  
  161.  
  162. 10. APPENDIX B - PRIMARY DOMAIN CONTROLLER LOCATION PROTOCOL..........29
  163.  
  164.  
  165.  
  166. 11. APPENDIX C - SUMMARY OF SPECIAL NETBIOS NAMES.....................31
  167.  
  168.  
  169.  11.1 REGISTERED UNIQUE NAMES ........................................31
  170.  
  171.  11.2 REGISTERED GROUP NAMES .........................................32
  172.  
  173.  
  174. 12. APPENDIX D - BROWSING PROTOCOL EVOLUTION..........................32
  175.  
  176.  
  177.  
  178.  
  179. 1. Introduction
  180.  
  181. The CIFS/E (CIFS extensions for enterprise networks) family of protocols
  182. includes a protocol for "browsing". Browsing is a mechanism for
  183.  
  184. Leach, Naik                                              [Page 3]
  185.  
  186.  
  187. INTERNET-DRAFT    CIFS/E Browser Protocol        January 10, 1997
  188.  
  189.  
  190. discovering servers that are running particular services (not just CIFS
  191. file services). Servers are organized into named groups called
  192. "domains", which form browsing scopes. This document specifies version
  193. 1.15 of  the browsing protocol. It also specifies the mailslot protocol,
  194. because the browsing protocol depends on it (and  is the only CIFS/E
  195. protocol which does).
  196.  
  197. This document uses the traditional RFC keywords MUST, SHOULD, etc., (now
  198. documented in [Bradner 96]) to indicate requirement levels for
  199. interoperability.
  200.  
  201. Note: This document is about CIFS/E browsers and has nothing to do
  202. whatsoever with Web browsers such as Internet Explorer and Netscape
  203. Navigator. This is a specification for persons interested in
  204. implementing a browser server or client that can inter-operate with
  205. other CIFS/E browsers and clients.
  206.  
  207. 2. Prerequisites
  208.  
  209. . Familiarity with Common Internet File System specification (CIFS) in
  210.   general and the Transact2 SMB as well as Remote Administration
  211.   Protocol in particular [CIFS 96]
  212. . Familiarity with concepts of subnets and NETBIOS [RFC 1001].
  213.   
  214. Additional information about browsing may be found in the MSDN articles
  215. _Browsing and Windows 95_ Parts I, II and III. These articles cover
  216. considerations for browser deployment, especially in a WAN environment.
  217.  
  218. 3. Browser Overview
  219.  
  220. Hosts involved in the browsing process can be separated into two
  221. distinct groups, browser clients and browser servers (often referred to
  222. simply as _browsers_).
  223.  
  224. A browser is a server which maintains information about servers _
  225. primarily the domain they are in and the services that they are running
  226. -- and about domains. Browsers may assume several different roles in
  227. their lifetimes, and dynamically switch between them.
  228.  
  229.  Browser clients are of two types: workstations and (non-browser)
  230. servers. In the context of browsing, workstations query browsers for the
  231. information they contain; servers supply browsers the information by
  232. registering with them. Note that, at times, browsers may themselves
  233. behave as browser clients and query other browsers.
  234.  
  235. For the purposes of this specification, a domain is simply a name with
  236. which to associate a group of resources such as computers, servers and
  237. users. Domains allow a convenient means for browser clients to restrict
  238. the scope of a search when they query browser servers. Every domain has
  239. a _master_ server called the Primary Domain Controller (PDC) that
  240. manages various  activities within the domain.
  241.  
  242. One browser for each domain on a subnet is designated the Local Master
  243. Browser for that domain. Servers in its domain on the subnet register
  244.  
  245. Leach, Naik                                              [Page 4]
  246.  
  247.  
  248. INTERNET-DRAFT    CIFS/E Browser Protocol        January 10, 1997
  249.  
  250.  
  251. with it, as do the Local Master Browsers for other domains on the
  252. subnet. It uses these registrations to maintain authoritative
  253. information about its domain on its subnet. If there are other subnets
  254. in the network, it also knows the name of the server running the
  255. domain's Domain Master Browser; it registers with it, and uses it to
  256. obtain information about the rest of the network (see below).
  257.  
  258. Clients on a subnet query browsers designated as the Backup Browsers for
  259. the subnet (not the Master Browser). Backup Browsers maintain a copy of
  260. the information on the Local Master Browser; they get it by periodically
  261. querying the Local Master Browser for all of its information. Clients
  262. find the Backup Browsers by asking the Local Master Browser. Clients are
  263. expected to spread their queries evenly across Backup Browsers to
  264. balance the load.
  265.  
  266. The Local Master Browser is dynamically elected automatically. Multiple
  267. Backup Browser Servers may exist per subnet; they are selected from
  268. among the potential browser servers by the Local Master Browser, which
  269. is configured to select enough to handle the expected query load.
  270.  
  271. When the re are multiple subnets, a Domain Master Browser is assigned
  272. the task of keeping the multiple subnets in synchronization. The Primary
  273. Domain Controller (PDC) always acts as the Domain Master Browser. The
  274. Domain Master Browser periodically acts as a client and queries all the
  275. Local Master Browsers for its domain, asking them for a list containing
  276. all the domains and all the servers in their domain known within their
  277. subnets; it merges all the replies into a single master list. This
  278. allows a Domain Master Browser server to act as a collection point for
  279. inter-subnet browsing information. Local Master Browsers periodically
  280. query the Domain Master Browser to retrieve the network-wide information
  281. it maintains.
  282.  
  283. When a domain spans only a single subnet, there will not be any distinct
  284. Local Master Browser; this role will be handled by the Domain Master
  285. Browser. Similarly, the Domain Master Browser is always the Local Master
  286. Browser for the subnet it is on.
  287.  
  288. When a browser client suspects that the Local Master Browser has failed,
  289. the client will instigate an election in which the browser servers
  290. participate, and some browser servers may change roles.
  291.  
  292. Some characteristics of a good browsing mechanism include:
  293. . minimal network traffic
  294. . minimum server discovery time
  295. . minimum change discovery latency
  296. . immunity to machine failures
  297.  
  298. Historically, Browser implementations had been very closely tied to
  299. NETBIOS and datagrams. The early implementations caused a lot of
  300. broadcast traffic. See Appendix D for an overview that presents how the
  301. Browser specification evolved.
  302.  
  303.  
  304.  
  305.  
  306. Leach, Naik                                              [Page 5]
  307.  
  308.  
  309. INTERNET-DRAFT    CIFS/E Browser Protocol        January 10, 1997
  310.  
  311.  
  312. 4. Browsing Protocol Architecture
  313.  
  314. This section first describes the how the browsing protocol is layered,
  315. then describes the roles of clients, servers, and browsers in the
  316. browsing subsystem.
  317.  
  318. 4.1 Layering of Browsing Protocol Requests
  319.  
  320. Most of the browser functionality is implemented using mailslots.
  321. Mailslots provide a mechanism for fast, unreliable unidirectional data
  322. transfer; they are named via ASCII _mailslot (path) name_. Mailslots are
  323. implemented using the CIFS Transact SMB which is encapsulated in a
  324. NETBIOS datagram. Browser protocol requests are sent to browser specific
  325. mailslots using some browser-specific NETBIOS names. These datagrams can
  326. either be unicast or broadcast, depending on whether the NETBIOS name is
  327. a _unique name_ or a _group name_. Various data structures, which are
  328. detailed subsequently within this document, flow as the data portion of
  329. the Transact SMB.
  330.  
  331. Here is an example of a generic browser SMB, showing how a browser
  332. request is encapsulated in a TRANSACT SMB request. Note that the PID,
  333. TID, MID, UID, and Flags are all 0 in mailslot requests.
  334.  
  335.  
  336.  
  337.  
  338.  
  339.  
  340.  
  341.  
  342.  
  343.  
  344.  
  345.  
  346.  
  347.  
  348.  
  349.  
  350.  
  351.  
  352.  
  353.  
  354.  
  355.  
  356.  
  357.  
  358.  
  359.  
  360.  
  361.  
  362.  
  363.  
  364.  
  365.  
  366.  
  367. Leach, Naik                                              [Page 6]
  368.  
  369.  
  370. INTERNET-DRAFT    CIFS/E Browser Protocol        January 10, 1997
  371.  
  372.  
  373. SMB: C transact, File = \MAILSLOT\BROWSE
  374.   SMB: SMB Status = Error Success
  375.     SMB: Error class = No Error
  376.     SMB: Error code = No Error
  377.   SMB: Header: PID = 0x0000 TID = 0x0000 MID = 0x0000 UID = 0x0000
  378.     SMB: Tree ID   (TID) = 0 (0x0)
  379.     SMB: Process ID  (PID) = 0 (0x0)
  380.     SMB: User ID   (UID) = 0 (0x0)
  381.     SMB: Multiplex ID (MID) = 0 (0x0)
  382.     SMB: Flags Summary = 0 (0x0)
  383.   SMB: Command = C transact
  384.     SMB: Word count = 17
  385.     SMB: Word parameters
  386.     SMB: Total parm bytes = 0
  387.     SMB: Total data bytes = 33
  388.     SMB: Max parm bytes = 0
  389.     SMB: Max data bytes = 0
  390.     SMB: Max setup words = 0
  391.     SMB: Transact Flags Summary = 0 (0x0)
  392.       SMB: ...............0 = Leave session intact
  393.       SMB: ..............0. = Response required
  394.     SMB: Transact timeout = 0 (0x0)
  395.     SMB: Parameter bytes = 0 (0x0)
  396.     SMB: Parameter offset = 0 (0x0)
  397.     SMB: Data bytes = 33 (0x21)
  398.     SMB: Data offset = 86 (0x56)
  399.     SMB: Setup word count = 3
  400.     SMB: Setup words
  401.     SMB: Mailslot opcode = Write mailslot
  402.     SMB: Transaction priority = 1
  403.     SMB: Mailslot class = Unreliable (broadcast)
  404.     SMB: Byte count = 50
  405.     SMB: Byte parameters
  406.     SMB: Path name = \MAILSLOT\BROWSE
  407.     SMB: Transaction data
  408.   SMB: Data: Number of data bytes remaining = 33 (0x0021)
  409.  
  410. Note the SMB command is Transact, the opcode within the Transact SMB is
  411. Mailslot Write, and the browser data structure is carried as the
  412. Transact data.
  413. The Transaction data begins with an opcode, that signifies the operation
  414. and determines the size and structure of data that follows. This opcode
  415. is named as per one of the below:
  416.  
  417. HostAnnouncement         1
  418. AnnouncementRequest      2
  419. RequestElection          8
  420. GetBackupListReq         9
  421. GetBackupListResp        10
  422. BecomeBackup             11
  423. DomainAnnouncment        12
  424. MasterAnnouncement       13
  425. LocalMasterAnnouncement  15
  426.  
  427.  
  428. Leach, Naik                                              [Page 7]
  429.  
  430.  
  431. INTERNET-DRAFT    CIFS/E Browser Protocol        January 10, 1997
  432.  
  433.  
  434. Browser datagrams are often referred to as simply browser frames. The
  435. frames are in particular, referred to by the name of the opcode within
  436. the Transaction data e.g. a GetBackupListReq browser frame, a
  437. RequestElection browser frame, etc.
  438.  
  439. The structures that are sent as the data portion of the Transact SMB are
  440. described in section(s) 6.2 through 6.12 in this document. These
  441. structures are tightly packed, i.e. there are no intervening pad bytes
  442. in the structure, unless they are explicitly described as being there.
  443. All quantities are sent in native Intel format and multi-byte values are
  444. transmitted least significant byte first.
  445.  
  446. Besides mailslots and Transaction SMBs, the other important piece of the
  447. browser architecture is the NetServerEnum2 request. This request that
  448. allows an application to interrogate a Browser Server and obtain a
  449. complete list of resources (servers, domains, etc) known to that Browser
  450. server. Details of the NetServerEnum2 request are presented in section
  451. 6.4. Some examples of the NetServerEnum2 request being used are when a
  452. Local Master Browser sends a NetServerEnum2 request to the Domain Master
  453. Browser and vice versa. Another example is when a browser client sends a
  454. NetServerEnum2 request to a Backup Browser server.
  455.  
  456.  
  457. 4.2  Browser Client
  458.  
  459. A browser client is a system running applications which may wish to
  460. query for a list of servers for a particular domain (often its own) or a
  461. list of all the domains in the network. (For example, such an
  462. application is launched when a user clicks on the Network Neighborhood
  463. icon on a Windows machine.) A browser client may send a NetServerEnum2
  464. request (see section 6.4) to any Backup Browser serving that domain to
  465.  
  466. obtain such information.
  467.  
  468. A browser client SHOULD keep a list of a few Backup Browsers for its own
  469. domain; it MAY cache lists of Backup Browsers for other domains if it
  470. browses them frequently, or it may obtain them upon demand. The
  471. objective is to minimize the cost of locating Backup Browsers each time
  472. it wants to make a NetServerEnum2 request.
  473.  
  474. A browser client SHOULD distribute its NetServerEnum2 requests randomly
  475. among all the Backup Browsers for a domain in its list. The objective is
  476. to enable multiple Backup Browsers to effectively handle high browsing
  477. loads.
  478.  
  479. A browser client SHOULD NOT send its NetServerEnum2 requests directly to
  480.  
  481. a Master Browser. Browser clients unilaterally sending NetServerEnum2
  482.  
  483. requests directly to Master Browsers will result in unavoidable
  484.  
  485. congestive collapse in a large enough network.
  486.  
  487.  
  488.  
  489. Leach, Naik                                              [Page 8]
  490.  
  491.  
  492. INTERNET-DRAFT    CIFS/E Browser Protocol        January 10, 1997
  493.  
  494.  
  495.  
  496.  
  497. A browser client can locate browser servers for the domain it wants to
  498. browse by sending a GetBackupListRequest frame to the Local Master
  499. Browser for that domain and waiting for a GetBackupListResponse frame.
  500. See section 6.2 and section 6.3, respectively. Once the Local Master
  501. Browser server responds with a list of Backup Browser servers, the
  502. client should choose several at random from within the response, and
  503. cache them. If there is no response after a delay, the
  504. GetBackupListRequest frame may be retransmitted. The delay MUST be at
  505. least twice the expected service time, and the delay should be doubled
  506. after each time-out.
  507.  
  508. In case the Local Master Browser for a domain fails to respond to the
  509.  
  510. GetBackupListRequest, the browser client may attempt to retrieve a list
  511.  
  512. of Backup Browsers by sending a GetBackupListRequest  frame directly to
  513.  
  514. the Domain Master Browser for that domain. It can find the Domain Master
  515.  
  516. Browser using the method described in appendix B.
  517.  
  518.  
  519.  
  520. A browser client SHOULD force an election by sending a RequestElection
  521. frame (see section 6.7) if it does not get a response to a
  522.  
  523. GetBackupListRequest for its own domain after several retransmissions,
  524. since it must be assumed that the Local Master browser has crashed.
  525. Details of the election process are in sections 6.7 and 6.8.
  526.  
  527. 4.3 Non-Browser Server
  528.  
  529. A non-browser server is a server that has some resource(s) or service(s)
  530. it wishes to advertise as being available using the browsing protocol.
  531. Examples of non-browser servers would be an SQL server, print server,
  532. etc.
  533.  
  534. A non-browser server MUST periodically send a HostAnnouncement browser
  535. frame, specifying the type of resources or services it is advertising.
  536. Details are in section 6.5.
  537.  
  538. A non-browser server SHOULD announce itself relatively frequently when
  539. it first starts up in order to make its presence quickly known to the
  540. browsers and thence to potential clients. The frequency of the
  541. announcements SHOULD then be gradually stretched, so as to minimize
  542. network traffic. Typically,  non-browser servers announce themselves
  543. once every minute upon start up and then gradually adjust the frequency
  544. of the announcements to once every 12 minutes.
  545.  
  546. A non-browser server SHOULD send a HostAnnouncement browser frame
  547. specifying a type of  0 just prior to shutting down, to allow it to
  548. quickly be removed from the list of available servers.
  549.  
  550. Leach, Naik                                              [Page 9]
  551.  
  552.  
  553. INTERNET-DRAFT    CIFS/E Browser Protocol        January 10, 1997
  554.  
  555.  
  556.  
  557. A non-browser server MUST receive and process AnnouncementRequest frames
  558. from the Local Master Browser, and MUST respond with a HostAnnouncement
  559. frame, after a delay chosen randomly from the interval [0,30] seconds.
  560. AnnouncementRequests typically happen when a Local Master Browser starts
  561. up with an empty list of servers for the domain, and wants to fill it
  562. quickly. The 30 second range for responses prevents the Master Browser
  563. from becoming overloaded and losing replies, as well as preventing the
  564. network from being flooded with responses.
  565.  
  566. 4.4  Browser Servers
  567.  
  568. The following sections describe the roles of the various types of
  569. browser servers.
  570.  
  571. 4.4.1  Potential Browser Server
  572.  
  573. A Potential Browser server is a browser server that is capable of being
  574. a Backup Browser server or Master Browser server, but is not currently
  575. fulfilling either of those roles.
  576.  
  577. A Potential Browser MUST set type SV_TYPE_POTENTIAL_BROWSER (see section
  578. 6.4.1) in its HostAnnouncement until it is ready to shut down. In its
  579.  
  580. last HostAnnouncement frame before it shuts down, it SHOULD specify a
  581. type of  0.
  582.  
  583. A Potential Browser server MUST receive and process BecomeBackup frames
  584. (see section 6.9) and become a backup browser upon their receipt.
  585.  
  586.  
  587. A Potential Browser MUST participate in browser elections (see section
  588. 6.8).
  589.  
  590.  
  591. 4.4.2  Backup Browser
  592.  
  593. Backup Browser servers are a subset of the Potential Browsers that have
  594. been chosen by the Master Browser on their subnet to be the Backup
  595. Browsers for the subnet.
  596.  
  597. A Backup Browser MUST set type SV_TYPE_BACKUP_BROWSER (see section
  598. 6.4.1) in its HostAnnouncement until it is ready to shut down. In its
  599.  
  600. last HostAnnouncement frame before it shuts down, it SHOULD specify a
  601. type of  0.
  602.  
  603. A Backup Browser MUST listen for a LocalMasterAnnouncement frame (see
  604. section 6.10) from the Local Master Browser, and use it to set the name
  605.  
  606. of the Master Browser it queries for the server and domain lists.
  607.  
  608. A  Backup Browsers MUST periodically make a NetServerEnum2 request of
  609. the Master Browser on its subnet for its domain to get a list of servers
  610.  
  611. Leach, Naik                                             [Page 10]
  612.  
  613.  
  614. INTERNET-DRAFT    CIFS/E Browser Protocol        January 10, 1997
  615.  
  616.  
  617. in that domain, as well as a list of domains. The period is a
  618. configuration option balancing currency of the information with network
  619. traffic costs _ a typical value is 15 minutes.
  620.  
  621. A Backup Browser SHOULD force an election by sending a RequestElection
  622. frame (see section 6.7) if it does not get a response to its periodic
  623.  
  624. NetServeEnum2 request to the Master Browser.
  625.  
  626. A Backup Browser MUST receive and process NetServerEnum2 requests from
  627. browser clients, for its own domain and others. If the request is for a
  628. list of servers in its domain, or for a list of domains, it can answer
  629. from its internal lists. If the request is for a list of servers in a
  630. domain different than the one it serves, it sends a NetServerEnum2
  631. request to the Domain Master Browser for that domain (which it can in
  632. find in its list of domains and their Domain Master Browsers).
  633.  
  634. A Backup Browser MUST participate in browser elections (see section
  635. 6.8).
  636.  
  637.  
  638. 4.4.3 Master Browser
  639.  
  640. Master Browsers are responsible for:
  641. . indicating it is a Master Browser
  642. . receiving server announcements and building a list of such servers
  643.   and keeping it reasonably up-to-date.
  644. . returning lists of Backup Browsers to browser clients.
  645. . ensuring an appropriate number of Backup Browsers are available.
  646. . announcing their existence to other Master Browsers on their subnet,
  647.   to the Domain Master Browser for their domain, and to all browsers in
  648.   their domain on their subnet
  649. . forwarding requests for lists of servers on other domains to the
  650.   Master Browser for that domain
  651. . keeping a list of domains in its subnet
  652. . synchronizing with the Domain Master Browser (if any) for its domain
  653. . participating in browser elections
  654. . ensuring that there is only one Master Browser on its subnet
  655.  
  656. A Master Browser MUST set type SV_TYPE_MASTER_BROWSER (see section
  657. 6.4.1) in its HostAnnouncement until it is ready to shut down. In its
  658.  
  659. last HostAnnouncement frame before it shuts down, it SHOULD specify a
  660. type of  0.
  661.  
  662. A Master Browser MUST receive and process HostAnnouncement frames from
  663. servers, adding the server name and other information to its servers
  664. list; it must mark them as _authoritative_ entries. Periodically, it
  665.  
  666. MUST check all local server entries to see if a server's
  667. HostAnnouncement has timed out (no HostAnnouncement received for three
  668. times the periodicity the server gave in the last received
  669. HostAnnouncement) and remove timed-out servers from its list.
  670.  
  671.  
  672. Leach, Naik                                             [Page 11]
  673.  
  674.  
  675. INTERNET-DRAFT    CIFS/E Browser Protocol        January 10, 1997
  676.  
  677.  
  678. A Master Browser MUST receive and process DomainAnnouncement frames (see
  679. section 6.12) and maintain the domain names and their associated (Local)
  680.  
  681. Master Browsers in its internal domain list until they time out; it must
  682. mark these as _authoritative_ entries. Periodically, it MUST check all
  683.  
  684. local domain entries to see if a server's DomainAnnouncement has timed
  685. out (no DomainAnnouncement received for three times the periodicity the
  686. server gave in the last received DomainAnnouncement) and remove timed-
  687. out servers from its list.
  688.  
  689. A Master Browser MUST receive and process GetBackupListRequest frames
  690. from clients, returning GetBackupListResponse frames containing a list
  691. of the Backup Servers for its domain.
  692.  
  693. A Master Browser MUST eventually send BecomeBackup frames (see section
  694. 6.9) to one or more Potential Browser servers to increase the number of
  695. Backup Browsers if there are not enough Backup Browsers to handle the
  696. anticipated query load. Note: possible good times for checking for
  697. sufficient backup browsers are after being elected, when timing out
  698. server HostAnnouncements, and when receiving a server's HostAnnouncement
  699. for the first time.
  700.  
  701. A Master Browser MUST periodically announce itself and the domain it
  702. serves to other (Local) Master Browsers on its subnet, by sending a
  703. DomainAnnouncement frame (see section 6.12) to its subnet.
  704.  
  705. A Master Browser MUST send a MasterAnnouncement frame (see section 6.11)
  706. to the Domain Master Browser after it is first elected, and periodically
  707. thereafter. This informs the Domain Master Browser of the presence of
  708. all the Master Browsers.
  709.  
  710. A Master Browser MUST periodically announce itself to all browsers for
  711. its domain on its subnet by sending a LocalMasterAnnouncement frame (see
  712. section 6.10).
  713.  
  714. A Master Browser MUST receive and process NetServerEnum2 requests from
  715. browser clients, for its own domain and others. If the request is for a
  716. list of servers in its domain, or for a list of domains, it can answer
  717. from its internal lists. Entries in its list marked _authoritative_ MUST
  718.  
  719. have the SV_TYPE_LOCAL_LIST_ONLY bit set in the returned results; it
  720. must be clear for all other entries. If the request is for a list of
  721. servers in a domain different than the one it serves, it sends a
  722. NetServerEnum2 request to the Domain Master Browser for that domain
  723. (which it can in find in its list of domains and their Domain Master
  724. Browsers).
  725.  
  726.     Note: The list of servers that the Master Browser maintains and
  727.     returns to the Backup Browsers, is limited in size to 64K of
  728.     data. This will limit the number of systems that can be in a
  729.     browse list in a single workgroup or domain to approximately two
  730.     thousand systems.
  731.  
  732.  
  733. Leach, Naik                                             [Page 12]
  734.  
  735.  
  736. INTERNET-DRAFT    CIFS/E Browser Protocol        January 10, 1997
  737.  
  738.  
  739. A Master Browser SHOULD request all servers to register with it by
  740. sending an AnnouncementRequest frame, if, on becoming the Master Browser
  741. by winning an election, its server list is empty. Otherwise, clients
  742. might get an incomplete list of servers until the servers' periodic
  743. registrations fill the server list.
  744.  
  745. If the Master Browser on a subnet is not the Primary Domain Controller
  746. (PDC), then it is a Local Master Browser.
  747.  
  748. A Local Master Browser MUST periodically synchronize with the Domain
  749. Master Browser (which is the PDC). This synchronization is performed by
  750. making a NetServerEnum2 request to the Domain Master Browser and merging
  751. the results with its list of servers and domains. An entry from the
  752. Domain Master Browser should be marked "non-local", and must not
  753. overwrite an entry with the same name marked _authoritative_. The Domain
  754.  
  755. Master Browser is located as specified in Appendix B.
  756.  
  757. A Master Browser MUST participate in browser elections (see section
  758. 6.8).
  759.  
  760.  
  761. A Master Browser for a domain "D" MUST, after winning an election,
  762.  
  763. register the NetBIOS unique name D(1d).
  764.  
  765.  
  766.  
  767. A Master Browser for a domain "D" MUST, after losing an election,
  768.  
  769. unregister the NetBIOS unique name D(1d), and do so quickly enough that
  770.  
  771. the winning browser can successfully register it.
  772.  
  773.  
  774.  
  775. A Master Browser MUST, if it receives a HostAnnouncement,
  776. DomainAnnouncement, or LocalMasterAnnouncement frame another system that
  777. claims to be the Master Browser for its domain, demote itself from
  778. Master Browser and force an election. This ensures that there is only
  779. ever one Master Browser in each workgroup or domain.
  780.  
  781. A Master Browser SHOULD, if it loses an election, become a Backup
  782. Browser (without being told to do so by the new Master Browser). Since
  783. it has more up-to-date information in its lists than a Potential
  784. Browser, it is more efficient to have it be a Backup Browser than to
  785. promote a Potential Browser.
  786.  
  787.  
  788. 4.4.3.1 Preferred Master Browser
  789.  
  790. A Preferred Master Browser supports exactly the same protocol elements
  791. as a Potential Browser, except as follows.
  792.  
  793.  
  794. Leach, Naik                                             [Page 13]
  795.  
  796.  
  797. INTERNET-DRAFT    CIFS/E Browser Protocol        January 10, 1997
  798.  
  799.  
  800. A Preferred Master Browser MUST always force an election when it starts
  801. up.
  802.  
  803. A Preferred Master Browser MUST participate in browser elections (see
  804. section 6.8).
  805.  
  806.  
  807. A Preferred Master Browser MUST set the Preferred Master bit in the
  808. RequestElection frame (see section 6.7) to bias the election in its
  809.  
  810. favor.
  811.  
  812. A Preferred Master Browser SHOULD, if it loses an election,
  813. automatically become a Backup Browser, without being told to do so by
  814. the Master Browser.
  815.  
  816. 4.4.4 Domain Master Browser
  817.  
  818. A Domain Master Browser for a domain MUST act as a Local Master Browser
  819.  
  820. for its subnet. Thus, it acts exactly like a Local Master Browser,
  821.  
  822. except where required to act differently by this section.
  823.  
  824.  
  825.  
  826. A Domain Master Browser MUST set type SV_TYPE_DOMAIN_MASTER (see section
  827.  
  828. 6.4.1) in its HostAnnouncement until it is ready to shut down. In its
  829.  
  830. last HostAnnouncement frame before it shuts down, it SHOULD specify a
  831.  
  832. type of  0.
  833.  
  834.  
  835.  
  836. A Domain Master Browser for a domain MUST receive and process
  837.  
  838. MasterAnnouncement frames from Local Master Browsers of its domain, and
  839.  
  840. keep a list of all the Local Master Browsers in its domain.
  841.  
  842.  
  843.  
  844. A Domain Master Browser MUST periodically synchronize with the Local
  845.  
  846. Master Browsers for its domain. This synchronization is performed by
  847.  
  848. making a NetServerEnum2 request to each Local Master Browser for its
  849.  
  850. "authoritative" entries and merging the results into a master list for
  851.  
  852. the whole domain.
  853.  
  854.  
  855. Leach, Naik                                             [Page 14]
  856.  
  857.  
  858. INTERNET-DRAFT    CIFS/E Browser Protocol        January 10, 1997
  859.  
  860.  
  861.  
  862.  
  863. A Domain Master Browser MUST eventually purge an entry from its master
  864.  
  865. list if:
  866.  
  867. . it was originally received from a Local Master Browser
  868.  
  869. . it has not appeared in any list obtained from a Local Master Browser
  870.  
  871.   for an implementation specific amount of time
  872.  
  873. . it has not received any MasterAnnouncement or HostAnnouncement for
  874.  
  875.   the server or domain specified by the entry
  876.  
  877.  
  878.  
  879. A Domain Master Browser MUST set the PDC bit in the RequestElection
  880.  
  881. frame (see section 6.7) to bias the election in its favor.
  882.  
  883.  
  884.  
  885. A Domain Master Browser MAY be configured with a list of domains for
  886.  
  887. which it is to support cross-domain browsing. It MUST periodically
  888.  
  889. discover or validate the name of the Domain Master Browser for each such
  890.  
  891. domain using the mechanism in appendix B, and add this information to
  892.  
  893. its list of domains and their Domain Master Browsers.
  894.  
  895.  
  896. 5. Mailslot Protocol Specification
  897.  
  898. The only transaction allowed to a mailslot is a mailslot write. Mailslot
  899. writes requests are encapsulated in CIFS TRANSACT SMBs and sent to a
  900.  
  901. specified NetBIOS name. The following table shows the interpretation of
  902.  
  903. the TRANSACT SMB parameters for a mailslot transaction:
  904.  
  905.  Name            Value               Description
  906.  Command         SMB_COM_TRANSACTION
  907.  Name            <name>              STRING name of mail slot to write;
  908.                                      must start with "\MAILSLOT\"
  909.  SetupCount      3                   Always 3 for mailslot writes
  910.  Setup[0]        1                   Command code == write mailslot
  911.  Setup[1]        Ignored
  912.  Setup[2]        Ignored
  913.  TotalDataCount  n                   Size of data in bytes to write to
  914.                                      the mailslot
  915.  
  916. Leach, Naik                                             [Page 15]
  917.  
  918.  
  919. INTERNET-DRAFT    CIFS/E Browser Protocol        January 10, 1997
  920.  
  921.  
  922.  Data[ n ]                           The data to write to the mailslot
  923.  
  924.  
  925. When it is specified that a mailslot message  is "sent to NetBIOS name X
  926.  
  927. and mailslot Y" it means that a NetBIOS datagram  (as specified in
  928.  
  929. section 4.4.2 of [RFC 1002]) is sent whose
  930.  
  931. . MSG_TYPE is DIRECT_UNIQUE_DATAGRAM if the NetBIOS name is a unique
  932.  
  933.   name
  934.  
  935. . MSG_TYPE is DIRECT_GROUP_DATAGRAM if the NetBIOS name is a group name
  936.  
  937. . SOURCE_NAME field is the NetBIOS name of the sending system
  938.  
  939. . DESTINATION_NAME is X
  940.  
  941. . USER_DATA field contains an SMB_COM_TRANSACTION SMB (as specified in
  942.  
  943.   the CIFS spec) with its fields as specified in the table above.
  944.  
  945.  (or the equivalent, if the NetBIOS service in use is over a protocol
  946.  
  947. other than as specified by RFC 1001/1002.)
  948.  
  949.  
  950.  
  951. In order to receive mailslot messages, a system MUST have done a NetBIOS
  952.  
  953. registration (as per section 5.2 of RFC 1001) of the DESTINATION_NAME to
  954.  
  955. which the message was sent.
  956.  
  957.  
  958.  
  959. Before sending a mailslot message, the sending system SHOULD have done a
  960.  
  961. NetBIOS registration of the SOURCE_NAME in the message to be sent.
  962.  
  963.  
  964. 6. Browser Protocol Specification
  965.  
  966. As already explained, browser datagrams are also referred to as Browser
  967. frames. What distinguishes one browser frame from another is the opcode
  968.  
  969. that is carried as the data portion of the Transact SMB, and the NETBIOS
  970. name and mailslot to which the browser frame is sent.  Browser frames
  971.  
  972. are often referred to by the symbolic name of the opcode that is within
  973.  
  974. the data portion of the Transact SMB. The following sections describe
  975. the various Browser frames.
  976.  
  977. Leach, Naik                                             [Page 16]
  978.  
  979.  
  980. INTERNET-DRAFT    CIFS/E Browser Protocol        January 10, 1997
  981.  
  982.  
  983. 6.1 NETBIOS Name Notation
  984.  
  985. NAME(xx) denotes the ASCII string "NAME," padded with spaces (0x20) to
  986. 15 bytes, with a hex xx value in the 16th byte. For example, the
  987. notation FOOBAR(15) indicates a NETBIOS name consisting of the bytes:
  988.     [69,79,79,65,64,82,20,20,20,20,20,20,20,20,20, 15]
  989.  
  990. Names that are placeholders and that need to be substituted with their
  991. actual values are bracketed within <>. Thus the string <Domain> would
  992. become _Redmond_ if the domain under consideration is named _Redmond_.
  993. Details of the various NETBIOS names used for browsing are described in
  994. Appendix C.
  995.  
  996. 6.2 GetBackupListRequest Browser Frame
  997.  
  998. The GetBackupListRequest frame is sent by a browser client to any Master
  999. Browser for a domain to allow the client to learn the identities of
  1000. Backup Browsers. To get the list of Backup Browsers for domain "D" from
  1001.  
  1002. the Local Master Browser for that domain,  the GetBackupListRequest
  1003.  
  1004. browser frame is sent to to NETBIOS unique name D(1d) and mailslot
  1005.  
  1006. _\MAILSLOT\MSBROWSE_. To get the list of Backup Browsers for domain "D"
  1007.  
  1008. from the Domain Master Browser for that domain,  the
  1009.  
  1010. GetBackupListRequest browser frame is sent to to NETBIOS unique name
  1011.  
  1012. D(1b) and mailslot _\MAILSLOT\MSBROWSE_. The definition of the
  1013.  
  1014. GetBackupListRequest frame is:
  1015.  
  1016.     struct {
  1017.         unsigned char OpCode;
  1018.         unsigned short Token;
  1019.     }
  1020.  
  1021. where :
  1022.  
  1023. OpCode identifies this structure as a request to return a list of Backup
  1024. servers. Opcode is defined as GetBackupListRequest and has a value of
  1025. decimal 9.
  1026.  
  1027. Token is a handle of meaning only to the client issuing the browser
  1028. frame. The Local Master Browser will return this token unmodified in the
  1029. response. The client should use this to distinguish replies to multiple
  1030. outstanding GetBackupList requests. This implies that every
  1031. GetBackupListRequest should have an unique handle, at least within the
  1032. outstanding lifetime of a request.
  1033.  
  1034. The expected response is a GetBackupListResponse frame (see next
  1035. section).
  1036.  
  1037.  
  1038. Leach, Naik                                             [Page 17]
  1039.  
  1040.  
  1041. INTERNET-DRAFT    CIFS/E Browser Protocol        January 10, 1997
  1042.  
  1043.  
  1044. 6.3 GetBackupListResponse Browser Frame
  1045.  
  1046. The GetBackupListResponse frame is sent by a Master Browser in response
  1047. to a GetBackupListRequest frame. The GetBackupListResponse frame is sent
  1048.  
  1049. to the NETBIOS unique name in the SOURCE_NAME of the mailslot message
  1050.  
  1051. containing the GetBackupListRequest and mailslot \MAILSLOT\LANMAN. Note:
  1052.  
  1053. this name is not part of the body of the request and on many systems the
  1054.  
  1055. Master Browser will need to obtain this name from the NetBIOS service.
  1056.  
  1057. The definition of the GetBackupListResponse frame is:
  1058.  
  1059.     struct {
  1060.         unsigned char   OpCode;
  1061.         unsigned short  BackupServerCount;
  1062.         unsigned short  Token;
  1063.         unsigned char   BackupServerList[][]
  1064.     }
  1065. where:
  1066.      Opcode __Identifies this structure as a backup list.
  1067.  
  1068.      BackupServerCount __Specifies the number of backup servers
  1069.          that follow this list.
  1070.  
  1071.      Token __Is returned unmodified to the client. This is used by
  1072.          the client to associate an incoming BackupListResponse
  1073.          with its BackupListRequest.
  1074.  
  1075.      BackupServerList __ASCII backup servers. Each server name is
  1076.          null terminated and up to 16 bytes in length.
  1077.  
  1078.  
  1079. 6.4 The NetServerEnum2 RAP Service
  1080.  
  1081. The NetServerEnum2 RAP service lists all computers of the specified type
  1082. or types that are visible in the specified domains. It may also
  1083. enumerate domains.
  1084.  
  1085. The following definition uses the notation and terminology defined in
  1086. the CIFS Remote Administration Protocol specification, which is required
  1087. in order to make it well-defined. The definition is:
  1088.  
  1089.  
  1090.  
  1091.  
  1092.  
  1093.  
  1094.  
  1095.  
  1096.  
  1097.  
  1098.  
  1099. Leach, Naik                                             [Page 18]
  1100.  
  1101.  
  1102. INTERNET-DRAFT    CIFS/E Browser Protocol        January 10, 1997
  1103.  
  1104.  
  1105.     unsigned short NetServerEnum2 (
  1106.         unsigned short  sLevel,
  1107.         RCVBUF      pbBuffer,
  1108.         RCVBUFLEN   cbBuffer,
  1109.         ENTCOUNT        pcEntriesRead,
  1110.         unsigned short *pcTotalAvail,
  1111.         unsigned long  fServerType,
  1112.         char        *pszDomain,
  1113.     );
  1114.  
  1115. where:
  1116.  
  1117.    sLevel specifies the level of detail (0 or 1) requested.
  1118.  
  1119.    pbBuffer points to the buffer to receive the returned data. If the
  1120.    function is successful, the buffer contains a sequence of
  1121.    server_info_x structures, where x is 0 or 1, depending on the
  1122.    level of detail requested.
  1123.  
  1124.    cbBuffer specifies the size, in bytes, of the buffer pointed to by
  1125.    the pbBuffer parameter.
  1126.  
  1127.    pcEntriesRead points to a 16 bit variable that receives a count of
  1128.    the number of servers enumerated in the buffer. This count is
  1129.    valid only if NetServerEnum2 returns the NERR_Success or
  1130.    ERROR_MORE_DATA values.
  1131.  
  1132.    pcTotal Avail points to a 16 bit variable that receives a count of
  1133.    the total number of available entries. This count is valid only if
  1134.    NetServerEnum2 returns the NERR_Success or ERROR_MORE_DATA values.
  1135.  
  1136.     fServerType specifies the type or types of computers to enumerate.
  1137.     Computers that match at least one of the specified types are
  1138.     returned in the buffer. Possible values are defined in the request
  1139.     parameters section.
  1140.  
  1141.    pszDomain points to a null-terminated string that contains the
  1142.    name of the workgroup in which to enumerate computers of the
  1143.    specified type or types. If the pszDomain parameter is a null
  1144.    string or a null pointer, servers are enumerated for the current
  1145.    domain of the computer.
  1146.  
  1147. 6.4.1 Transaction Request Parameters section
  1148.  
  1149. The Transaction request parameters section in this instance contains:
  1150. . The 16 bit function number for NetServerEnum2 which is 104.
  1151. . The parameter descriptor string which is "WrLehDz".
  1152. . The data descriptor string for the (returned) data which is "B16" for
  1153.   level detail 0 or "B16BBDz" for level detail 1.
  1154. . The actual parameters as described by the parameter descriptor
  1155.   string.
  1156.  
  1157. The parameters are:
  1158.  
  1159.  
  1160. Leach, Naik                                             [Page 19]
  1161.  
  1162.  
  1163. INTERNET-DRAFT    CIFS/E Browser Protocol        January 10, 1997
  1164.  
  1165.  
  1166. . A 16 bit integer with a value of 0 or 1 (corresponding to the "W" in
  1167.   the parameter descriptor string. This represents the level of detail
  1168.   the server is expected to return
  1169. . A 16 bit integer that contains the size of the receive buffer.
  1170. . A 32 bit integer that represents the type of servers the function
  1171.   should enumerate. The possible values may be any of the following or
  1172.   a combination of the following:
  1173.  
  1174. SV_TYPE_WORKSTATION        0x00000001 All workstations
  1175. SV_TYPE_SERVER             0x00000002 All servers
  1176. SV_TYPE_SQLSERVER          0x00000004 Any server running with SQL
  1177.                                       server
  1178. SV_TYPE_DOMAIN_CTRL        0x00000008 Primary domain controller
  1179. SV_TYPE_DOMAIN_BAKCTRL     0x00000010 Backup domain controller
  1180. SV_TYPE_TIME_SOURCE        0x00000020 Server running the timesource
  1181.                                       service
  1182. SV_TYPE_AFP                0x00000040 Apple File Protocol servers
  1183. SV_TYPE_NOVELL             0x00000080 Novell servers
  1184. SV_TYPE_DOMAIN_MEMBER      0x00000100 Domain Member
  1185. SV_TYPE_PRINTQ_SERVER      0x00000200 Server sharing print queue
  1186. SV_TYPE_DIALIN_SERVER      0x00000400 Server running dialin service.
  1187. SV_TYPE_XENIX_SERVER       0x00000800 Xenix server
  1188. SV_TYPE_NT                 0x00001000 NT server
  1189. SV_TYPE_WFW                0x00002000 Server running Windows for
  1190.                                       Workgroups
  1191. SV_TYPE_SERVER_NT          0x00008000 Windows NT non DC server
  1192. SV_TYPE_POTENTIAL_BROWSER  0x00010000 Server that can run the browser
  1193.                                       service
  1194. SV_TYPE_BACKUP_BROWSER     0x00020000 Backup browser server
  1195. SV_TYPE_MASTER_BROWSER     0x00040000 Master browser server
  1196. SV_TYPE_DOMAIN_MASTER      0x00080000 Domain Master Browser server
  1197. SV_TYPE_LOCAL_LIST_ONLY    0x40000000 Enumerate only
  1198.  
  1199.                                       entries marked "local"local
  1200.  
  1201.                                       entries (marked
  1202.  
  1203.                                       "authoritative"). This is
  1204.  
  1205.                                       meaningful only for the
  1206.  
  1207.                                       NetServerEnum2 request and
  1208.  
  1209.                                       should be ignored within the
  1210.  
  1211.                                       NetServerEnum2 response.
  1212.  
  1213.  
  1214. SV_TYPE_DOMAIN_ENUM        0x80000000 Enumerate Domains. The pszDomain
  1215.                                       parameter must be NULL.
  1216.  
  1217. . A null terminated ASCII string representing the pszDomain parameter
  1218.   described above
  1219.  
  1220.  
  1221. Leach, Naik                                             [Page 20]
  1222.  
  1223.  
  1224. INTERNET-DRAFT    CIFS/E Browser Protocol        January 10, 1997
  1225.  
  1226.  
  1227. 6.4.2 Transaction Request Data section
  1228.  
  1229. There is no data or auxiliary data to send as part of the request.
  1230.  
  1231. 6.4.3 Transaction Response Parameters section
  1232.  
  1233. The transaction response parameters section consists of:
  1234. . A 16 bit word indicating the return status. The possible values are:
  1235.  
  1236. Code                   Value  Description
  1237. NERR_Success           0      No errors encountered
  1238. ERROR_MORE_DATA        234    Additional data is available
  1239. NERR_ServerNotStarted  2114   The RAP service on the remote computer
  1240.                               is not running
  1241. NERR_BadTransactConfig 2141   The server is not configured for
  1242.                               transactions, IPC$ is not shared
  1243.  
  1244. . A 16 bit "converter" word.
  1245. . A 16 bit number representing the number of entries returned.
  1246. . A 16 bit number representing the total number of available entries.
  1247.   If the supplied buffer is large enough, this will equal the number of
  1248.   entries returned.
  1249.  
  1250. 6.4.4 Transaction Response Data section
  1251.  
  1252. The return data section consists of a number of SHARE_INFO_1 structures.
  1253. The number of such structures present is determined by the third entry
  1254. (described above) in the return parameters section.
  1255.  
  1256. At level detail 0, the Transaction response data section contains a
  1257. number of SERVER_INFO_0 data structure. The number of such structures is
  1258. equal to the 16 bit number returned by the server in the third parameter
  1259. in the Transaction response parameter section. The SERVER_INFO_0 data
  1260. structure is defined as:
  1261.  
  1262.     struct SERVER_INFO_0 {
  1263.         char        sv0_name[16];
  1264.     };
  1265.  
  1266.  where:
  1267.  
  1268.    sv0_name is a null-terminated string that specifies the name of a
  1269.    computer or domain .
  1270.  
  1271. At level detail 1, the Transaction response data section contains a
  1272. number of SERVER_INFO_1 data structure. The number of such structures is
  1273. equal to the 16 bit number returned by the server in the third parameter
  1274. in the Transaction response parameter section. The SERVER_INFO_1 data
  1275. structure is defined as:
  1276.  
  1277.  
  1278.  
  1279.  
  1280.  
  1281.  
  1282. Leach, Naik                                             [Page 21]
  1283.  
  1284.  
  1285. INTERNET-DRAFT    CIFS/E Browser Protocol        January 10, 1997
  1286.  
  1287.  
  1288.     struct SERVER_INFO_1 {
  1289.         char            sv1_name[16];
  1290.         char            sv1_version_major;
  1291.         char            sv1_version_minor;
  1292.         unsigned long   sv1_type;
  1293.         char        *sv1_comment_or_master_browser;
  1294.     };
  1295.  
  1296.    sv1_name contains a null-terminated string that specifies the name
  1297.    of a computer, or a domain name if SV_TYPE_DOMAIN_ENUM is set in
  1298.    sv1_type.
  1299.  
  1300.    sv1_version_major whatever was specified in the HostAnnouncement
  1301.    or DomainAnnouncement frame with which the entry was registered.
  1302.  
  1303.    sv1_version_minor whatever was specified in the HostAnnouncement
  1304.    or DomainAnnouncement frame with which the entry was registered.
  1305.  
  1306.    sv1_type specifies the type of software the computer is running.
  1307.    The member can be one or a combination of the values defined above
  1308.    in the Transaction request parameters section for fServerType.
  1309.  
  1310.  
  1311.    sv1_comment_or_master_browser points to a null-terminated string. If
  1312.    the sv1_type indicates that the entry is for a domain, this
  1313.    specifies the name of server running the domain master browser;
  1314.    otherwise, it specifies a comment describing the server. The comment
  1315.    can be a null string or the pointer may be a null pointer.
  1316.  
  1317.    In case there are multiple SERVER_INFO_1 data structures to
  1318.    return, the server may put all these fixed length structures in
  1319.    the return buffer, leave some space and then put all the variable
  1320.    length data (the actual value of the sv1_comment strings) at the
  1321.    end of the buffer.
  1322.  
  1323. There is no auxiliary data to receive.
  1324.  
  1325. 6.5 HostAnnouncement Browser Frame
  1326.  
  1327. To advertise its presence, i.e. to publish itself as being available, a
  1328. non-browser server sends a HostAnnouncement browser frame. If the server
  1329. is a member of domain "D", this frame is sent to the NETBIOS unique name
  1330. D(1d) and mailslot _\MAILSLOT\MSBROWSE_. The definition of  the
  1331. HostAnnouncement frame is:
  1332.  
  1333.  
  1334.  
  1335.  
  1336.  
  1337.  
  1338.  
  1339.  
  1340.  
  1341.  
  1342.  
  1343. Leach, Naik                                             [Page 22]
  1344.  
  1345.  
  1346. INTERNET-DRAFT    CIFS/E Browser Protocol        January 10, 1997
  1347.  
  1348.  
  1349.     struct {
  1350.         unsigned char   Opcode;
  1351.         unsigned char   UpdateCount;
  1352.         unsigned long   Periodicity;
  1353.         unsigned char   ServerName[];
  1354.         unsigned char   VersionMajor;
  1355.         unsigned char   VersionMinor;
  1356.         unsigned long   Type;
  1357.         unsigned long   Signature;
  1358.         unsigned char   Comment[];
  1359.     }
  1360.  
  1361. where:
  1362.      Opcode __Identifies this structure as a browser server
  1363.          announcement and is defined as HostAnnouncement with a
  1364.          value of decimal 1.
  1365.  
  1366.      UpdateCount _ must be sent as zero and ignored on receipt.
  1367.  
  1368.      Periodicity __The announcement frequency of the server (in
  1369.          milliseconds). The server will be removed from the browse
  1370.  
  1371.          list if it has not been heard from in 3X its announcement
  1372.          frequency. In no case will the server be removed from the
  1373.          browse list before the period 3X has elapsed. Actual
  1374.          implementations may take more than 3X to actually remove
  1375.          the server from the browse list.
  1376.  
  1377.      ServerName __Null terminated ASCII server name (up to 16 bytes
  1378.          in length). This name SHOULD be registered with NetBIOS by
  1379.  
  1380.          the server offering the services specified in the Type
  1381.  
  1382.          field.
  1383.  
  1384.  
  1385.      VersionMajor __The major version number of the OS the server
  1386.          is running. it will be returned by NetServerEnum2.
  1387.  
  1388.      VersionMinor __The minor version number of the OS the server
  1389.          is running. This is entirely informational and does not
  1390.          have any significance for the browsing protocol.
  1391.  
  1392.      Type __Specifies the type of the server. The server type bits
  1393.          are specified in the NetServerEnum2 section.
  1394.  
  1395.      Signature __ The browser protocol minor version number in the
  1396.          low 8 bits, the browser protocol major version number in
  1397.          the next higher 8 bits and the signature 0xaa55 in the
  1398.          high 16 bits of this field. Thus, for this version of the
  1399.          browser protocol (1.15) this field has the value
  1400.          0xaa55010f. This may used to isolate browser servers that
  1401.          are running out of revision browser software; otherwise,
  1402.          it is ignored.
  1403.  
  1404. Leach, Naik                                             [Page 23]
  1405.  
  1406.  
  1407. INTERNET-DRAFT    CIFS/E Browser Protocol        January 10, 1997
  1408.  
  1409.  
  1410.      Comment __Null terminated ASCII comment for the server.
  1411.          Limited to 43 bytes.
  1412.  
  1413. When a non-browser server starts up, it announces itself in the manner
  1414. described once every minute. The frequency of these statements is
  1415. gradually stretched to once every 12 minutes.
  1416.  
  1417. Note: older non-browser servers in a domain "D" sent HostAnnouncement
  1418. frames to the NETBIOS group name D(00). Non-Browser servers supporting
  1419. version 1.15 of the browsing protocol SHOULD NOT use this NETBIOS name,
  1420. but for backwards compatibility Master Browsers MAY receive and process
  1421. HostAnnouncement frames on this name as described above for D(1d).
  1422.  
  1423. 6.6 AnnouncementRequest Browser Frame
  1424.  
  1425. When a Master Browser starts up and its browse list is empty, it may
  1426. force all servers to announce themselves by broadcasting an
  1427. AnnouncementRequest frame. If the Master Browser serves domain "D", the
  1428. AnnouncementRequest frame is broadcast using the NETBIOS group name
  1429. D(00) and mailslot _\MAILSLOT\LANMAN_. The definition of the
  1430. AnnouncementRequest frame is:
  1431.  
  1432.     struct {
  1433.         unsigned char Opcode;
  1434.         unsigned char  ResponseComputerName[];
  1435.     };
  1436.  
  1437.      Opcode __Identifies this structure as an announcement request
  1438.          and is defined as AnnounceMent Request with a value of
  1439.          decimal 2.
  1440.  
  1441.      ResponseComputerName __Specifies the name of the computer to
  1442.          send the server announcement to and is up to 16 bytes in
  1443.          length. This is ignored . The response to this browser
  1444.          frame is a HostAnnouncement browser frame as described
  1445.          immediately above. That browser frame does not use this
  1446.          parameter at all.
  1447.  
  1448. Recipients of this packet should reply by sending an HostAnnouncement
  1449. frame as described above. The reply should be sent within a randomly
  1450. determined time period that may have a duration of up to 30 seconds. The
  1451. random delay ensures that the Master Browser who sent out the packet
  1452. does not get flooded with replies, all at the same time.
  1453.  
  1454. 6.7 RequestElection Browser Frame
  1455.  
  1456. To force the election of a new Master Browser for a domain, any browser
  1457. client or server can broadcast a RequestElection frame. If the election
  1458. is for domain "D", the frame is broadcast using the NETBIOS group name
  1459. D(1e) and mailslot _\MAILSLOT\MSBROWSE_. The definition of the
  1460. RequestElection frame is:
  1461.  
  1462.  
  1463.  
  1464.  
  1465. Leach, Naik                                             [Page 24]
  1466.  
  1467.  
  1468. INTERNET-DRAFT    CIFS/E Browser Protocol        January 10, 1997
  1469.  
  1470.  
  1471.      struct {
  1472.         unsigned char Opcode;
  1473.         unsigned char Version;
  1474.         unsigned long Criteria;
  1475.         unsigned long TimeUp;
  1476.         unsigned long MustBeZero;
  1477.         unsigned char ServerName[];
  1478.      }
  1479.  
  1480.     Opcode __Identifies this structure as an election request, and is
  1481.         defined as RequestElection, with a value of decimal 8.
  1482.  
  1483.     Version __Specifies the version of this election packet. This is a
  1484.         constant and always has the value 0x00010f00
  1485.  
  1486.     Criteria __Specifies the election criteria of the sender. Produced
  1487.         by OR'ing together the Version and the following:
  1488.  
  1489.     OS info:
  1490.         Windows for Workgroups & Windows 95:    0x00000000
  1491.         Windows NT:                     0x01000000
  1492.         Windows NT Server:                  0x02000000
  1493.     Role:
  1494.         PDC:                                0x00000080
  1495.         Preferred Master:                   0x00000008
  1496.         Running Master:                 0x00000004
  1497.         Backup Browser which was
  1498.         recently a Master Browser:          0x00000002
  1499.         Running Backup Browser:             0x00000001
  1500.         Using NBNS for NETBIOS:             0x00000020
  1501.  
  1502.     The following masks can be used to isolate parts of the Criteria:
  1503.  
  1504.     Operating System Type Mask              0xFF000000
  1505.     Election Protocol Version Mask:         0x00FFFF00
  1506.     Per version criteria mask:              0x000000FF
  1507.  
  1508.  
  1509.     TimeUp __The number of seconds that the server has been up.
  1510.  
  1511.     MustBeZero__Must be zero.
  1512.  
  1513.     ServerName __Null terminated ASCII server name (up to 16 bytes in
  1514.         length).
  1515.  
  1516.  
  1517. 6.8 Browser Elections
  1518.  
  1519. All browsers for a domain "D" MUST listen for RequestElection frames on
  1520. the group name D(1e) and mailslot _\MAILSLOT\MSBROWSE_.
  1521.  
  1522. Elections proceed in rounds. A round is initiated when a RequestElection
  1523. frame is sent. When a Browser receives a RequestElection frame, it
  1524. determines if it has won the round using the following rules:
  1525.  
  1526. Leach, Naik                                             [Page 25]
  1527.  
  1528.  
  1529. INTERNET-DRAFT    CIFS/E Browser Protocol        January 10, 1997
  1530.  
  1531.  
  1532.  
  1533.         If it has lost an election in the last several seconds, it loses
  1534.         If its election Version is greater than the senders election
  1535.         Version, it wins
  1536.         Else if its election Criteria (including the election version)
  1537.         is greater than the senders Criteria, it wins
  1538.         Else if it has been up longer than the sender, it wins
  1539.         Else if its name is lexically lower than the sender's name, it
  1540.         wins
  1541.                 (I.e., at this point, a sever named A will become Master
  1542.                 Browser over a server named X)
  1543.  
  1544. (Note that many browsers which receive a RequestElection frame may win a
  1545. round.)
  1546.  
  1547. Each time it wins a round,  a browser sends out a RequestElection frame,
  1548. after a delay based on the browser's current role in the domain:
  1549. . Master Browsers and Domain Master Browsers delay for 100 ms.
  1550. . Backup Browsers delay for an amount randomly chosen from the interval
  1551.   200-600 ms.
  1552. . All other browsers delay for an amount randomly chosen from the
  1553.   interval 800-3000 ms.
  1554.  
  1555. If a browser loses a round it drops out of the election by ignoring
  1556. RequestElection frames until it receives a LocalMasterAnnouncement frame
  1557. that tells which system is the new Master Browser.
  1558.  
  1559. If a browser wins 4 rounds in a row, it becomes the Master Browser.
  1560.  
  1561. 6.9 BecomeBackup Browser Frame
  1562.  
  1563. If a Local Master Browser for a domain "D" wants to promote a Potential
  1564. Browser to Backup Browser, it broadcasts a  BecomeBackup frame using the
  1565. NETBIOS group name D(1e) and the _\MAILSLOT\MSBROWSE_ mailslot. The
  1566. definition of the BecomeBackup frame is:
  1567.  
  1568.     struct {
  1569.         unsigned char Opcode;
  1570.         unsigned char BrowserToPromote[];
  1571.     }
  1572.  
  1573.      Opcode __ Identifies this structure as a browser server
  1574.          announcement, is defined as BecomeBackup, with a value of
  1575.          decimal 11
  1576.  
  1577.      BrowserToPromote __Specifies the name of the browser server to
  1578.          be promoted to backup. Maximum of 16 bytes in length.
  1579.  
  1580.  
  1581. 6.10 LocalMasterAnnouncement Browser Frame
  1582.  
  1583. A Local Master Browser for a domain announces itself to all the other
  1584. browsers in its domain that are on its subnet using the
  1585. LocalMasterAnnouncement frame. If the Local Master Browser serves domain
  1586.  
  1587. Leach, Naik                                             [Page 26]
  1588.  
  1589.  
  1590. INTERNET-DRAFT    CIFS/E Browser Protocol        January 10, 1997
  1591.  
  1592.  
  1593. "D", the LocalMasterAnnouncement frame is broadcast using the NETBIOS
  1594. group name D(1e) and the mailslot _\MAILSLOT\MSBROWSE_. The definition
  1595. of the LocalMasterAnnouncement frame is:
  1596.  
  1597.     struct {
  1598.         unsigned char Opcode;
  1599.         unsigned char UpdateCount;
  1600.         unsigned long Periodicity;
  1601.         unsigned char ServerName[];
  1602.         unsigned char VersionMajor;
  1603.         unsigned char VersionMinor;
  1604.         unsigned long Type;
  1605.         unsigned long Signature;
  1606.         unsigned char Comment[];
  1607.     }
  1608.  
  1609. where:
  1610.      Opcode __Identifies this structure as a browser server
  1611.          announcement and is defined as LocalMasterAnnouncement
  1612.          with a value of decimal 15.
  1613.  
  1614.      UpdateCount _ must be sent as zero and ignored on receipt.
  1615.  
  1616.      Periodicity __The announcement frequency of the browser (in
  1617.          milliseconds). The browser will be removed from the browse
  1618.  
  1619.          list if it has not been heard from in 3X its announcement
  1620.          frequency. In no case will the server be removed from the
  1621.          browse list before the period 3X has elapsed. Actual
  1622.          implementations may take more than 3X to remove the server
  1623.          from the browse list.
  1624.  
  1625.      ServerName __Null terminated ASCII server name (up to 16 bytes
  1626.          in length).
  1627.  
  1628.      VersionMajor __The major version of the OS the server is
  1629.          running. This value is informational and irrelevant to the
  1630.          browsing protocol.
  1631.  
  1632.      VersionMinor __The minor version of the OS the server is
  1633.          running. This value is informational and irrelevant to the
  1634.          browsing protocol.
  1635.  
  1636.      Type __Specifies the type of the browser. The type bits are
  1637.          specified in the description of NetServerEnum2.
  1638.  
  1639.      Signature __ The browser protocol minor version number in the
  1640.          low 8 bits, the browser protocol major version number in
  1641.          the next higher 8 bits and the signature 0xaa55 in the
  1642.          high 16 bits of this field. This may used to isolate
  1643.          browser servers that are running out of revision browser
  1644.          software; otherwise, it is ignored. Thus, for this version
  1645.          of the browser protocol (1.15) this field has the value
  1646.          0xaa55010f.
  1647.  
  1648. Leach, Naik                                             [Page 27]
  1649.  
  1650.  
  1651. INTERNET-DRAFT    CIFS/E Browser Protocol        January 10, 1997
  1652.  
  1653.  
  1654.      Comment __Null terminated ASCII comment for the browser.
  1655.          Limited to 43 bytes.
  1656.  
  1657. Local Master Browsers do not need to send HostAnnouncement frames; the
  1658. LocalMasterAnnouncement accomplishes that function.
  1659.  
  1660. 6.11 MasterAnnouncement browser Frame
  1661.  
  1662. The MasterAnnouncement frame is sent by a Local Master Browser to the
  1663. Domain Master Browser, which runs on the PDC. If the name of the PDC is
  1664. "PDCName", then the MasterAnnouncement frame is sent to the NETBIOS
  1665. unique name PDCName(00) and mailslot _\MAILSLOT\MSBROWSE_. Appendix B
  1666. describes how to determine the name of the Primary Domain Controller.
  1667. The definition of the MasterAnnouncement frame is::
  1668.  
  1669.     struct {
  1670.         unsigned char   Opcode;
  1671.         unsigned char  MasterBrowserServerName[];
  1672.     };
  1673.  
  1674.     Opcode __Identifies this structure as a master browser server
  1675.         announcement and is defined as MasterAnnouncement with a value
  1676.         of decimal 13.
  1677.  
  1678.     MasterBrowserServerName __Specifies the name of the master browser
  1679.         server (up to 16 bytes in length).
  1680.  
  1681.  
  1682. 6.12 DomainAnnouncement Browser Frame
  1683.  
  1684. Master Browsers (including Local Master Browsers and Domain Master
  1685. Browsers) announce the domain they serve to any other Master Browsers on
  1686. their subnet by broadcasting a DomainAnnouncement frame using the
  1687. NETBIOS group name _(01)(02)__MSBROWSE__(02)(01)_ and mailslot
  1688.  
  1689. _\MAILSLOT\MSBROWSE_. The definition of the DomainAnnouncement frame is:
  1690.  
  1691.     struct {
  1692.         unsigned char   Opcode;
  1693.         unsigned char UpdateCount;
  1694.         unsigned long Periodicity;
  1695.         unsigned char DomainName[];
  1696.         unsigned char VersionMajor;
  1697.         unsigned char VersionMinor;
  1698.         unsigned long Type;
  1699.         unsigned long Signature;
  1700.         unsigned char MasterBrowserName[];
  1701.     }
  1702.  
  1703. where:
  1704.      Opcode __Identifies this structure as a browser server
  1705.          announcement and is defined as DomainAnnouncement with a
  1706.          value of decimal 12.
  1707.  
  1708.  
  1709. Leach, Naik                                             [Page 28]
  1710.  
  1711.  
  1712. INTERNET-DRAFT    CIFS/E Browser Protocol        January 10, 1997
  1713.  
  1714.  
  1715.      UpdateCount _ must be sent as zero and ignored on receipt.
  1716.  
  1717.      Periodicity __The announcement frequency of the domain (in
  1718.          milliseconds). The domain will be removed from the browse
  1719.  
  1720.          list if it has not been heard from in 3X its announcement
  1721.          frequency. In no case will the domain be removed from the
  1722.          browse list before the period 3X has elapsed. Actual
  1723.          implementations may take more than 3X to actually remove
  1724.          the domain from the browse list.
  1725.  
  1726.      DomainName __Null terminated ASCII server name (up to 16 bytes
  1727.          in length).
  1728.  
  1729.      VersionMajor __The major version of the OS the server is
  1730.          running. This value is informational and irrelevant to the
  1731.          browsing protocol.
  1732.  
  1733.      VersionMinor __The minor version of the OS the server is
  1734.          running. This value is informational and irrelevant to the
  1735.          browsing protocol.
  1736.  
  1737.      Type __Specifies the type of the server. The server type bits
  1738.          are specified in the previous section.
  1739.  
  1740.      Signature __ The browser protocol minor version number in the
  1741.          low 8 bits, the browser protocol major version number in
  1742.          the next higher 8 bits and the signature 0xaa55 in the
  1743.          high 16 bits of this field. This may used to isolate
  1744.          browser servers that are running out of revision browser
  1745.          software; otherwise, it is ignored. Thus, for this version
  1746.          of the browser protocol (1.15) this field has the value
  1747.          0xaa55010f.
  1748.  
  1749.      MasterBrowserName __Null terminated ASCII string containing
  1750.          the name of the master browser server for this domain.
  1751.  
  1752.  
  1753. 7. References
  1754. [CIFS 96}       I. Heizer, P. Leach, D. Perry, "Common Internet Files
  1755.         System Protocol (CIFS/1.0)", Internet-Draft, <draft-heizer-cifs-
  1756.         v1-spec-00.txt>,June 30, 1996 . (Work in Progress)
  1757. [RFC 1001]      K. Auerbach, A. Aggarwal, "Protocol Standard for a
  1758.         NETBIOS Service on a TCP/UDP Transport: Concepts and Methods",
  1759.         RFC 1001, Epilogue Technology, March 1987.
  1760. [Bradner 96]    S. Bradner, ""Key words for use in RFCs to Indicate
  1761.         Requirement Levels", Internet-Draft, <draft-bradner-key-words-
  1762.         02.txt>, August 1996 (Work in Progress)
  1763.  
  1764. 8. Author's Addresses
  1765. Paul Leach
  1766. Dilip Naik
  1767. Microsoft
  1768. 1 Microsoft Way
  1769.  
  1770. Leach, Naik                                             [Page 29]
  1771.  
  1772.  
  1773. INTERNET-DRAFT    CIFS/E Browser Protocol        January 10, 1997
  1774.  
  1775.  
  1776. Redmond, WA 98052
  1777.  paulle@microsoft.com
  1778. v-dilipn@microsoft.com
  1779.  
  1780. 9. Appendix A - Multi-net considerations
  1781.  
  1782. To begin with, let's clearly define what is meant by multiple networks
  1783. here. A computer can be running one or more network protocols on a
  1784. single network adapter card such as IP and IPX. Each of these is
  1785. considered to be a _network_ for the purposes of this paragraph. A
  1786. computer could also have multiple network adapter cards, and there could
  1787. be different protocols running on the different adapter cards, or even
  1788. the same protocol(s) on all of the adapter cards. So, more precisely, a
  1789. network here means a transport protocol per adapter card. A computer
  1790. with 2 physical network cards, running 2 different transport protocols
  1791. on each network card, would have 4 logical networks.
  1792.  
  1793. Browsers need to remember which logical network a server is located on.
  1794. When a client queries a browser for a list of servers, the browser
  1795. server needs to return a list of servers that are on the same logical
  1796. network on which the client query arrived at the browser server. So a
  1797. client that sends a browser frame using say IP will only be returned
  1798. information about servers that sent announcements using IP.
  1799. To summarize, browser servers need to understand the concept of logical
  1800. networks and track server announcements as well as client queries on a
  1801. per logical network basis.
  1802.  
  1803. 10. Appendix B - Primary Domain Controller Location Protocol
  1804.  
  1805. This appendix details how a client goes about locating a Primary Domain
  1806. Controller (PDC). The process is rather involved, because different
  1807. versions of the PDC have used different versions of the protocol, and
  1808. hence a client that does not know what protocol is supported by its PDC
  1809. has to try them all.
  1810.  
  1811. A Primary Domain Controller (PDC) for a domain "D" is located by sending
  1812. a mailslot message containing a NETLOGON_QUERY frame to a NETBIOS name
  1813. and mailslot "\NET\NETLOGON" and then waiting for a reply mailslot
  1814. message, which will be sent to the mailslot name specified by the client
  1815. in the NETLOGON_QUERY structure., and which will contain a
  1816. NETLOGON_RESPONSE structure. If there is no response after a delay, the
  1817. message may be retransmitted. The delay MUST be at least twice the
  1818. expected service time, and the delay should be doubled after each time-
  1819. out.
  1820.  
  1821. If a reply is received, the name of the PDC SHOULD be cached for future
  1822. use, so as time minimize network traffic. If no reply is received after
  1823. several retransmissions, the PDC may be declared to be unreachable, and
  1824. no further attempt to locate it should be made for a while (exactly how
  1825. long depends on the expected recovery time for a PDC and/or for the
  1826. network; typically a minute or so, but should be increased after each
  1827. failure).
  1828.  
  1829.  
  1830.  
  1831. Leach, Naik                                             [Page 30]
  1832.  
  1833.  
  1834. INTERNET-DRAFT    CIFS/E Browser Protocol        January 10, 1997
  1835.  
  1836.  
  1837. The only difference between versions of the protocol is the NETBIOS name
  1838. to which the message is sent, as follows:
  1839.  
  1840. NETBIOS     name      PDC's OS version
  1841. name        type      =============
  1842. =========== ========
  1843. D(1b)       unique    Windows NT 3.51 or later or compatible
  1844. D(1c)       group     Windows NT 3.1 or later or compatible
  1845. D(00)       group     all
  1846.  
  1847. Clients which are configured to know or are willing to assume what
  1848. version of the protocol their PDC is running may directly use the
  1849. appropriate NETBIOS name for that version. Otherwise, they SHOULD first
  1850. attempt D(1b), since it is unicast and creates the least network
  1851. traffic; if there is no response, then they SHOULD try the others. They
  1852. MAY try them in parallel.
  1853.  
  1854. The NETLOGON_QUERY structure is defined as :
  1855.  
  1856.     struct NETLOGON_QUERY{
  1857.         unsigned char   Opcode;
  1858.         char            ComputerName[];
  1859.         char            MailslotName[];
  1860.         unsigned short  Lm20Token;
  1861.     } ;
  1862.  
  1863.     Opcode __Identifies this structure as a NETLOGON_QUERY and has a
  1864.         value of 0x07.
  1865.  
  1866.     ComputerName __Specifies the ASCII name of the computer sending the
  1867.         query, and is up to 16 bytes in length. The response is sent to
  1868.         NETBIOS unique name <ComputerName>(00).
  1869.  
  1870.     MailslotName __Specifies the ASCII name of the mailslot to which the
  1871.         response is to be sent, and is up to 256 bytes in length; cannot
  1872.         be _\MAILSLOT\LANMAN_ or _\MAILSLOT\MSBROWSE_ or
  1873.         "\NET\NETLOGON".
  1874.  
  1875.     Lm20Token - has a value of 0xFFFF.
  1876.  
  1877.  
  1878. The response mailslot message contains a NETLOGON_RESPONSE data
  1879. structure that is defined as the following for non Windows NT clients:
  1880.  
  1881.     struct NETLOGON_RESPONSE
  1882.     {
  1883.         unsigned char   Opcode;
  1884.         char            PrimaryDCName[16];
  1885.         unsigned short  Lm20Token;
  1886.     };
  1887.  
  1888. where
  1889.     Opcode __Identifies this structure as a NETLOGON_RESPONSE and has a
  1890.         value of 0x12.
  1891.  
  1892. Leach, Naik                                             [Page 31]
  1893.  
  1894.  
  1895. INTERNET-DRAFT    CIFS/E Browser Protocol        January 10, 1997
  1896.  
  1897.  
  1898.     PrimaryDCName __Specifies the ASCII name of the Primary Domain
  1899.         Controller and is up to 16 bytes in length.
  1900.  
  1901.     Lm20Token - has a value of 0xFFFF
  1902.  
  1903. Note that this procedure to locate a Primary Domain Controller is
  1904. expensive in terms of network traffic. The Microsoft implementations
  1905. attempt to alleviate this by caching the PDC Name. Before using the
  1906. cached PDC Name, a NetServerEnum2 API is remoted to the PDC and a sanity
  1907. check is performed to ensure that the server type returned indicates a
  1908. Primary Domain Controller
  1909.  
  1910.  
  1911. 11. Appendix C - Summary of Special NETBIOS Names
  1912.  
  1913. This section details the various NETBIOS names that are involved in
  1914. sending and receiving browser frames. The different mailslots involved
  1915. in browsing (there are only 3) are described later on when the browser
  1916. frames are detailed.
  1917.  
  1918.  
  1919. 11.1 Registered unique names
  1920.  
  1921. <COMPUTER>(00)
  1922.      This name is used by all servers and clients to receive second
  1923.      class mailslot messages. A system must add this name in order to
  1924.      receive mailslot messages. The only browser requests that should
  1925.      appear on this name are BecomeBackup, GetBackupListResp,
  1926.      MasterAnnouncement, and LocalMasterAnnouncement frames. All other
  1927.      datagrams (other than the expected non-browser datagrams) may be
  1928.      ignored and an error logged.
  1929.  
  1930. <DOMAIN>(1d)
  1931.      This name is used to identify a master browser server for domain
  1932.      "DOMAIN" on a subnet.  A master browser server adds this name as a
  1933.      unique NETBIOS name when it becomes master browser. If the attempt
  1934.      to add the name fails, the master browser server assumes that there
  1935.      is another master in the domain and will fail to come up. It may
  1936.      log an error if the failure occurs more than 3 times in a row (this
  1937.      either indicates some form of network misconfiguration or a
  1938.      software error). The only requests that should appear on this name
  1939.      are GetBackupListRequest and HostAnnouncement requests. All other
  1940.      datagrams on this name may be ignored (and an error logged). If
  1941.      running a NETBIOS name service (NBNS, such as WINS), this name
  1942.      should not be registered with the NBNS.
  1943.  
  1944. <DOMAIN>(1b)
  1945.      This name is used to identify the Domain Master Browser for domain
  1946.      "DOMAIN" (which is also the primary domain controller). It is a
  1947.      unique name added only by the primary domain controller. The
  1948.      primary domain controller will respond to GetBackupListRequest on
  1949.      this name just as it responds to these requests on the <DOMAIN>(1d)
  1950.      name.
  1951.  
  1952.  
  1953. Leach, Naik                                             [Page 32]
  1954.  
  1955.  
  1956. INTERNET-DRAFT    CIFS/E Browser Protocol        January 10, 1997
  1957.  
  1958.  
  1959. 11.2 Registered group names
  1960.  
  1961. (01)(02)__MSBROWSE__(02)(01)
  1962.      This name is used by Master Browsers to announce themselves to the
  1963.      other Master Browsers on a subnet. It is added as a group name by
  1964.      all Master Browser servers. The only broadcasts that should appear
  1965.      on this name is DomainAnnouncement requests. All other datagrams
  1966.      can be ignored.
  1967.  
  1968. <DOMAIN>(00)
  1969.      This name is used by clients and servers in domain "DOMAIN" to
  1970.      process server announcements. The only requests that should appear
  1971.      on this name that the browser is interested in are
  1972.      AnnouncementRequest and NETLOGON_QUERY (to locate the PDC) packets.
  1973.      All other unidentifiable requests may be ignored (and an error
  1974.      logged).
  1975.  
  1976. <DOMAIN>(1e)
  1977.      This name is used for announcements to browsers for domain "DOMAIN"
  1978.      on a subnet. This name is registered by all the browser servers in
  1979.      the domain. The only requests that should appear on this name are
  1980.      RequestElection and AnnouncementRequest packets. All other
  1981.      datagrams may be ignored (and an error logged).
  1982.  
  1983. <DOMAIN>(1c)
  1984.      This name is registered by Primary Domain Controllers.
  1985.  
  1986.  
  1987. 12. Appendix D - Browsing Protocol Evolution
  1988.  
  1989. This Appendix details how the Microsoft Browser specification evolved
  1990. and correlates the evolution to specific Microsoft products.
  1991.  
  1992. The first browser implementation was with Lan Manager 1.0. Here, there
  1993. were no browser servers as such. Each client acted as its own browser
  1994. server. All servers announced themselves by means of datagrams and every
  1995. client and server listened for those datagrams. Obviously, the amount of
  1996. browser datagram traffic is fairly high and scales extremely poorly with
  1997. an increase in the number of servers.
  1998.  
  1999. The next major revision in the browser specification was with Windows
  2000. For Workgroups. This is where the concept of a browser server was really
  2001. introduced.
  2002.  
  2003. Windows NT 3.51 expanded upon what Windows For Workgroups built. Windows
  2004. NT 3.51 introduced the special NETBIOS name <Domain>(1b) that is
  2005. registered with WINS. Windows NT 3.51 also shipped a new redirector for
  2006. Windows For Workgroups that could take advantage of this new
  2007. <Domain>(1b) name.
  2008.  
  2009. In a domain which spans multiple broadcast areas, it may be necessary to
  2010. have a configuration file available that can resolve the address of a
  2011. browser server. This is because browsers rely on broadcasts for name
  2012. resolution, for historical reasons. But these name resolution broadcast
  2013.  
  2014. Leach, Naik                                             [Page 33]
  2015.  
  2016.  
  2017. INTERNET-DRAFT    CIFS/E Browser Protocol        January 10, 1997
  2018.  
  2019.  
  2020. packets are not forwarded by routers that span the multiple broadcast
  2021. areas of a domain. One example of such a configuration file is the
  2022. LMHOSTS file on Windows NT machines.
  2023.  
  2024.  
  2025.  
  2026.  
  2027.  
  2028.  
  2029.  
  2030.  
  2031.  
  2032.  
  2033.  
  2034.  
  2035.  
  2036.  
  2037.  
  2038.  
  2039.  
  2040.  
  2041.  
  2042.  
  2043.  
  2044.  
  2045.  
  2046.  
  2047.  
  2048.  
  2049.  
  2050.  
  2051.  
  2052.  
  2053.  
  2054.  
  2055.  
  2056.  
  2057.  
  2058.  
  2059.  
  2060.  
  2061.  
  2062.  
  2063.  
  2064.  
  2065.  
  2066.  
  2067.  
  2068.  
  2069.  
  2070.  
  2071.  
  2072.  
  2073.  
  2074.  
  2075. Leach, Naik                                             [Page 34]