[Docs] [txt|pdf] [Tracker] [Email] [Nits]

Versions: 00

Network Working Group                    Paul J. Leach, Microsoft
INTERNET-DRAFT                           Dilip C. Naik, Microsoft
draft-leach-cifs-browser-spec-00.txt
Category: Informational
Expires June 10, 1997                            January 10, 1997



                        CIFS/E Browser Protocol
                           Preliminary Draft




STATUS OF THIS MEMO

THIS IS A PRELIMINARY DRAFT OF AN INTERNET-DRAFT. IT DOES NOT REPRESENT
THE CONSENSUS OF ANY WORKING GROUP.

This document is an Internet-Draft. Internet-Drafts are working
documents of the Internet Engineering Task Force (IETF), its areas, and
its working groups. Note that other groups may also distribute working
documents as Internet-Drafts.

Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference material
or to cite them other than as "work in progress".

To learn the current status of any Internet-Draft, please check the
"1id-abstracts.txt" listing contained in the Internet-Drafts Shadow
Directories on ftp.is.co.za (Africa), nic.nordu.net (Europe),
munnari.oz.au (Pacific Rim), ds.internic.net (US East Coast), or
ftp.isi.edu (US West Coast).

Distribution of this document is unlimited. Please send comments to the
authors or the CIFS mailing list at <cifs@listserv.msn.com>. Discussions
of the mailing list are archived at
<URL:http://microsoft.ease.lsoft.com/archives/cifs.html>.

ABSTRACT

The CIFS/E (CIFS extensions for enterprise networks) family of protocols
includes a protocol for browsing. Browsing is a mechanism for
discovering servers that are running particular services (not just CIFS
file services). Servers are organized into named groups called domains,
which form browsing scopes. This document specifies version 1.15 of  the
browsing protocol. It also specifies the mailslot protocol, because the
browsing protocol depends on it (and  is the only CIFS/E protocol which
does).





Leach, Naik                                              [Page 1]

INTERNET-DRAFT    CIFS/E Browser Protocol        January 10, 1997


Table of Contents


1. INTRODUCTION........................................................3



2. PREREQUISITES.......................................................3



3. BROWSER OVERVIEW....................................................3



4. BROWSING PROTOCOL ARCHITECTURE......................................5


 4.1 LAYERING OF BROWSING PROTOCOL REQUESTS ...........................5

 4.2 BROWSER CLIENT ...................................................7

 4.3 NON-BROWSER SERVER ...............................................8

 4.4 BROWSER SERVERS ..................................................9

  4.4.1 Potential Browser Server ......................................9

  4.4.2 Backup Browser ................................................9

  4.4.3 Master Browser ...............................................10

  4.4.4 Domain Master Browser ........................................13


5. MAILSLOT PROTOCOL SPECIFICATION....................................13



6. BROWSER PROTOCOL SPECIFICATION.....................................15


 6.1 NETBIOS NAME NOTATION ...........................................15

 6.2 GETB     L         ACKUP ISTREQUEST BROWSER FRAME ..............................16

 6.3 GETBACKUPLISTRESPONSE BROWSER FRAME .............................16

 6.4 THE NETSERVERENUM2 RAP SERVICE ..................................17

  6.4.1 Transaction Request Parameters section .......................18

  6.4.2 Transaction Request Data section .............................19


Leach, Naik                                              [Page 2]

INTERNET-DRAFT    CIFS/E Browser Protocol        January 10, 1997


  6.4.3 Transaction Response Parameters section ......................19

  6.4.4 Transaction Response Data section ............................20

 6.5 HOSTANNOUNCEMENT BROWSER FRAME ..................................21

 6.6 ANNOUNCEMENTREQUEST BROWSER FRAME ...............................22

 6.7 REQUESTELECTION BROWSER FRAME ...................................23

 6.8 BROWSER ELECTIONS ...............................................24

 6.9 BECOMEBACKUP BROWSER FRAME ......................................25

 6.10 LOCALMASTERANNOUNCEMENT BROWSER FRAME ..........................25

 6.11 MASTERANNOUNCEMENT BROWSER FRAME ...............................27

 6.12 DOMAINANNOUNCEMENT BROWSER FRAME ...............................27


7. REFERENCES.........................................................28



8. AUTHOR'S ADDRESSES.................................................28



9. APPENDIX A - MULTI-NET CONSIDERATIONS..............................29



10. APPENDIX B - PRIMARY DOMAIN CONTROLLER LOCATION PROTOCOL..........29



11. APPENDIX C - SUMMARY OF SPECIAL NETBIOS NAMES.....................31


 11.1 REGISTERED UNIQUE NAMES ........................................31

 11.2 REGISTERED GROUP NAMES .........................................32


12. APPENDIX D - BROWSING PROTOCOL EVOLUTION..........................32




1. Introduction

The CIFS/E (CIFS extensions for enterprise networks) family of protocols
includes a protocol for "browsing". Browsing is a mechanism for

Leach, Naik                                              [Page 3]

INTERNET-DRAFT    CIFS/E Browser Protocol        January 10, 1997


discovering servers that are running particular services (not just CIFS
file services). Servers are organized into named groups called
"domains", which form browsing scopes. This document specifies version
1.15 of  the browsing protocol. It also specifies the mailslot protocol,
because the browsing protocol depends on it (and  is the only CIFS/E
protocol which does).

This document uses the traditional RFC keywords MUST, SHOULD, etc., (now
documented in [Bradner 96]) to indicate requirement levels for
interoperability.

Note: This document is about CIFS/E browsers and has nothing to do
whatsoever with Web browsers such as Internet Explorer and Netscape
Navigator. This is a specification for persons interested in
implementing a browser server or client that can inter-operate with
other CIFS/E browsers and clients.

2. Prerequisites

. Familiarity with Common Internet File System specification (CIFS) in
  general and the Transact2 SMB as well as Remote Administration
  Protocol in particular [CIFS 96]
. Familiarity with concepts of subnets and NETBIOS [RFC 1001].

Additional information about browsing may be found in the MSDN articles
_Browsing and Windows 95_ Parts I, II and III. These articles cover
considerations for browser deployment, especially in a WAN environment.

3. Browser Overview

Hosts involved in the browsing process can be separated into two
distinct groups, browser clients and browser servers (often referred to
simply as _browsers_).

A browser is a server which maintains information about servers _
primarily the domain they are in and the services that they are running
-- and about domains. Browsers may assume several different roles in
their lifetimes, and dynamically switch between them.

 Browser clients are of two types: workstations and (non-browser)
servers. In the context of browsing, workstations query browsers for the
information they contain; servers supply browsers the information by
registering with them. Note that, at times, browsers may themselves
behave as browser clients and query other browsers.

For the purposes of this specification, a domain is simply a name with
which to associate a group of resources such as computers, servers and
users. Domains allow a convenient means for browser clients to restrict
the scope of a search when they query browser servers. Every domain has
a _master_ server called the Primary Domain Controller (PDC) that
manages various  activities within the domain.

One browser for each domain on a subnet is designated the Local Master
Browser for that domain. Servers in its domain on the subnet register

Leach, Naik                                              [Page 4]

INTERNET-DRAFT    CIFS/E Browser Protocol        January 10, 1997


with it, as do the Local Master Browsers for other domains on the
subnet. It uses these registrations to maintain authoritative
information about its domain on its subnet. If there are other subnets
in the network, it also knows the name of the server running the
domain's Domain Master Browser; it registers with it, and uses it to
obtain information about the rest of the network (see below).

Clients on a subnet query browsers designated as the Backup Browsers for
the subnet (not the Master Browser). Backup Browsers maintain a copy of
the information on the Local Master Browser; they get it by periodically
querying the Local Master Browser for all of its information. Clients
find the Backup Browsers by asking the Local Master Browser. Clients are
expected to spread their queries evenly across Backup Browsers to
balance the load.

The Local Master Browser is dynamically elected automatically. Multiple
Backup Browser Servers may exist per subnet; they are selected from
among the potential browser servers by the Local Master Browser, which
is configured to select enough to handle the expected query load.

When the re are multiple subnets, a Domain Master Browser is assigned
the task of keeping the multiple subnets in synchronization. The Primary
Domain Controller (PDC) always acts as the Domain Master Browser. The
Domain Master Browser periodically acts as a client and queries all the
Local Master Browsers for its domain, asking them for a list containing
all the domains and all the servers in their domain known within their
subnets; it merges all the replies into a single master list. This
allows a Domain Master Browser server to act as a collection point for
inter-subnet browsing information. Local Master Browsers periodically
query the Domain Master Browser to retrieve the network-wide information
it maintains.

When a domain spans only a single subnet, there will not be any distinct
Local Master Browser; this role will be handled by the Domain Master
Browser. Similarly, the Domain Master Browser is always the Local Master
Browser for the subnet it is on.

When a browser client suspects that the Local Master Browser has failed,
the client will instigate an election in which the browser servers
participate, and some browser servers may change roles.

Some characteristics of a good browsing mechanism include:
. minimal network traffic
. minimum server discovery time
. minimum change discovery latency
. immunity to machine failures

Historically, Browser implementations had been very closely tied to
NETBIOS and datagrams. The early implementations caused a lot of
broadcast traffic. See Appendix D for an overview that presents how the
Browser specification evolved.




Leach, Naik                                              [Page 5]

INTERNET-DRAFT    CIFS/E Browser Protocol        January 10, 1997


4. Browsing Protocol Architecture

This section first describes the how the browsing protocol is layered,
then describes the roles of clients, servers, and browsers in the
browsing subsystem.

4.1 Layering of Browsing Protocol Requests

Most of the browser functionality is implemented using mailslots.
Mailslots provide a mechanism for fast, unreliable unidirectional data
transfer; they are named via ASCII _mailslot (path) name_. Mailslots are
implemented using the CIFS Transact SMB which is encapsulated in a
NETBIOS datagram. Browser protocol requests are sent to browser specific
mailslots using some browser-specific NETBIOS names. These datagrams can
either be unicast or broadcast, depending on whether the NETBIOS name is
a _unique name_ or a _group name_. Various data structures, which are
detailed subsequently within this document, flow as the data portion of
the Transact SMB.

Here is an example of a generic browser SMB, showing how a browser
request is encapsulated in a TRANSACT SMB request. Note that the PID,
TID, MID, UID, and Flags are all 0 in mailslot requests.

































Leach, Naik                                              [Page 6]

INTERNET-DRAFT    CIFS/E Browser Protocol        January 10, 1997


SMB: C transact, File = \MAILSLOT\BROWSE
  SMB: SMB Status = Error Success
    SMB: Error class = No Error
    SMB: Error code = No Error
  SMB: Header: PID = 0x0000 TID = 0x0000 MID = 0x0000 UID = 0x0000
    SMB: Tree ID   (TID) = 0 (0x0)
    SMB: Process ID  (PID) = 0 (0x0)
    SMB: User ID   (UID) = 0 (0x0)
    SMB: Multiplex ID (MID) = 0 (0x0)
    SMB: Flags Summary = 0 (0x0)
  SMB: Command = C transact
    SMB: Word count = 17
    SMB: Word parameters
    SMB: Total parm bytes = 0
    SMB: Total data bytes = 33
    SMB: Max parm bytes = 0
    SMB: Max data bytes = 0
    SMB: Max setup words = 0
    SMB: Transact Flags Summary = 0 (0x0)
      SMB: ...............0 = Leave session intact
      SMB: ..............0. = Response required
    SMB: Transact timeout = 0 (0x0)
    SMB: Parameter bytes = 0 (0x0)
    SMB: Parameter offset = 0 (0x0)
    SMB: Data bytes = 33 (0x21)
    SMB: Data offset = 86 (0x56)
    SMB: Setup word count = 3
    SMB: Setup words
    SMB: Mailslot opcode = Write mailslot
    SMB: Transaction priority = 1
    SMB: Mailslot class = Unreliable (broadcast)
    SMB: Byte count = 50
    SMB: Byte parameters
    SMB: Path name = \MAILSLOT\BROWSE
    SMB: Transaction data
  SMB: Data: Number of data bytes remaining = 33 (0x0021)

Note the SMB command is Transact, the opcode within the Transact SMB is
Mailslot Write, and the browser data structure is carried as the
Transact data.
The Transaction data begins with an opcode, that signifies the operation
and determines the size and structure of data that follows. This opcode
is named as per one of the below:

HostAnnouncement         1
AnnouncementRequest      2
RequestElection          8
GetBackupListReq         9
GetBackupListResp        10
BecomeBackup             11
DomainAnnouncment        12
MasterAnnouncement       13
LocalMasterAnnouncement  15


Leach, Naik                                              [Page 7]

INTERNET-DRAFT    CIFS/E Browser Protocol        January 10, 1997


Browser datagrams are often referred to as simply browser frames. The
frames are in particular, referred to by the name of the opcode within
the Transaction data e.g. a GetBackupListReq browser frame, a
RequestElection browser frame, etc.

The structures that are sent as the data portion of the Transact SMB are
described in section(s) 6.2 through 6.12 in this document. These
structures are tightly packed, i.e. there are no intervening pad bytes
in the structure, unless they are explicitly described as being there.
All quantities are sent in native Intel format and multi-byte values are
transmitted least significant byte first.

Besides mailslots and Transaction SMBs, the other important piece of the
browser architecture is the NetServerEnum2 request. This request that
allows an application to interrogate a Browser Server and obtain a
complete list of resources (servers, domains, etc) known to that Browser
server. Details of the NetServerEnum2 request are presented in section
6.4. Some examples of the NetServerEnum2 request being used are when a
Local Master Browser sends a NetServerEnum2 request to the Domain Master
Browser and vice versa. Another example is when a browser client sends a
NetServerEnum2 request to a Backup Browser server.


4.2  Browser Client

A browser client is a system running applications which may wish to
query for a list of servers for a particular domain (often its own) or a
list of all the domains in the network. (For example, such an
application is launched when a user clicks on the Network Neighborhood
icon on a Windows machine.) A browser client may send a NetServerEnum2
request (see section 6.4) to any Backup Browser serving that domain to

obtain such information.

A browser client SHOULD keep a list of a few Backup Browsers for its own
domain; it MAY cache lists of Backup Browsers for other domains if it
browses them frequently, or it may obtain them upon demand. The
objective is to minimize the cost of locating Backup Browsers each time
it wants to make a NetServerEnum2 request.

A browser client SHOULD distribute its NetServerEnum2 requests randomly
among all the Backup Browsers for a domain in its list. The objective is
to enable multiple Backup Browsers to effectively handle high browsing
loads.

A browser client SHOULD NOT send its NetServerEnum2 requests directly to

a Master Browser. Browser clients unilaterally sending NetServerEnum2

requests directly to Master Browsers will result in unavoidable

congestive collapse in a large enough network.



Leach, Naik                                              [Page 8]

INTERNET-DRAFT    CIFS/E Browser Protocol        January 10, 1997




A browser client can locate browser servers for the domain it wants to
browse by sending a GetBackupListRequest frame to the Local Master
Browser for that domain and waiting for a GetBackupListResponse frame.
See section 6.2 and section 6.3, respectively. Once the Local Master
Browser server responds with a list of Backup Browser servers, the
client should choose several at random from within the response, and
cache them. If there is no response after a delay, the
GetBackupListRequest frame may be retransmitted. The delay MUST be at
least twice the expected service time, and the delay should be doubled
after each time-out.

In case the Local Master Browser for a domain fails to respond to the

GetBackupListRequest, the browser client may attempt to retrieve a list

of Backup Browsers by sending a GetBackupListRequest  frame directly to

the Domain Master Browser for that domain. It can find the Domain Master

Browser using the method described in appendix B.



A browser client SHOULD force an election by sending a RequestElection
frame (see section 6.7) if it does not get a response to a

GetBackupListRequest for its own domain after several retransmissions,
since it must be assumed that the Local Master browser has crashed.
Details of the election process are in sections 6.7 and 6.8.

4.3 Non-Browser Server

A non-browser server is a server that has some resource(s) or service(s)
it wishes to advertise as being available using the browsing protocol.
Examples of non-browser servers would be an SQL server, print server,
etc.

A non-browser server MUST periodically send a HostAnnouncement browser
frame, specifying the type of resources or services it is advertising.
Details are in section 6.5.

A non-browser server SHOULD announce itself relatively frequently when
it first starts up in order to make its presence quickly known to the
browsers and thence to potential clients. The frequency of the
announcements SHOULD then be gradually stretched, so as to minimize
network traffic. Typically,  non-browser servers announce themselves
once every minute upon start up and then gradually adjust the frequency
of the announcements to once every 12 minutes.

A non-browser server SHOULD send a HostAnnouncement browser frame
specifying a type of  0 just prior to shutting down, to allow it to
quickly be removed from the list of available servers.

Leach, Naik                                              [Page 9]

INTERNET-DRAFT    CIFS/E Browser Protocol        January 10, 1997



A non-browser server MUST receive and process AnnouncementRequest frames
from the Local Master Browser, and MUST respond with a HostAnnouncement
frame, after a delay chosen randomly from the interval [0,30] seconds.
AnnouncementRequests typically happen when a Local Master Browser starts
up with an empty list of servers for the domain, and wants to fill it
quickly. The 30 second range for responses prevents the Master Browser
from becoming overloaded and losing replies, as well as preventing the
network from being flooded with responses.

4.4  Browser Servers

The following sections describe the roles of the various types of
browser servers.

4.4.1  Potential Browser Server

A Potential Browser server is a browser server that is capable of being
a Backup Browser server or Master Browser server, but is not currently
fulfilling either of those roles.

A Potential Browser MUST set type SV_TYPE_POTENTIAL_BROWSER (see section
6.4.1) in its HostAnnouncement until it is ready to shut down. In its

last HostAnnouncement frame before it shuts down, it SHOULD specify a
type of  0.

A Potential Browser server MUST receive and process BecomeBackup frames
(see section 6.9) and become a backup browser upon their receipt.


A Potential Browser MUST participate in browser elections (see section
6.8).


4.4.2  Backup Browser

Backup Browser servers are a subset of the Potential Browsers that have
been chosen by the Master Browser on their subnet to be the Backup
Browsers for the subnet.

A Backup Browser MUST set type SV_TYPE_BACKUP_BROWSER (see section
6.4.1) in its HostAnnouncement until it is ready to shut down. In its

last HostAnnouncement frame before it shuts down, it SHOULD specify a
type of  0.

A Backup Browser MUST listen for a LocalMasterAnnouncement frame (see
section 6.10) from the Local Master Browser, and use it to set the name

of the Master Browser it queries for the server and domain lists.

A  Backup Browsers MUST periodically make a NetServerEnum2 request of
the Master Browser on its subnet for its domain to get a list of servers

Leach, Naik                                             [Page 10]

INTERNET-DRAFT    CIFS/E Browser Protocol        January 10, 1997


in that domain, as well as a list of domains. The period is a
configuration option balancing currency of the information with network
traffic costs _ a typical value is 15 minutes.

A Backup Browser SHOULD force an election by sending a RequestElection
frame (see section 6.7) if it does not get a response to its periodic

NetServeEnum2 request to the Master Browser.

A Backup Browser MUST receive and process NetServerEnum2 requests from
browser clients, for its own domain and others. If the request is for a
list of servers in its domain, or for a list of domains, it can answer
from its internal lists. If the request is for a list of servers in a
domain different than the one it serves, it sends a NetServerEnum2
request to the Domain Master Browser for that domain (which it can in
find in its list of domains and their Domain Master Browsers).

A Backup Browser MUST participate in browser elections (see section
6.8).


4.4.3 Master Browser

Master Browsers are responsible for:
. indicating it is a Master Browser
. receiving server announcements and building a list of such servers
  and keeping it reasonably up-to-date.
. returning lists of Backup Browsers to browser clients.
. ensuring an appropriate number of Backup Browsers are available.
. announcing their existence to other Master Browsers on their subnet,
  to the Domain Master Browser for their domain, and to all browsers in
  their domain on their subnet
. forwarding requests for lists of servers on other domains to the
  Master Browser for that domain
. keeping a list of domains in its subnet
. synchronizing with the Domain Master Browser (if any) for its domain
. participating in browser elections
. ensuring that there is only one Master Browser on its subnet

A Master Browser MUST set type SV_TYPE_MASTER_BROWSER (see section
6.4.1) in its HostAnnouncement until it is ready to shut down. In its

last HostAnnouncement frame before it shuts down, it SHOULD specify a
type of  0.

A Master Browser MUST receive and process HostAnnouncement frames from
servers, adding the server name and other information to its servers
list; it must mark them as _authoritative_ entries. Periodically, it

MUST check all local server entries to see if a server's
HostAnnouncement has timed out (no HostAnnouncement received for three
times the periodicity the server gave in the last received
HostAnnouncement) and remove timed-out servers from its list.


Leach, Naik                                             [Page 11]

INTERNET-DRAFT    CIFS/E Browser Protocol        January 10, 1997


A Master Browser MUST receive and process DomainAnnouncement frames (see
section 6.12) and maintain the domain names and their associated (Local)

Master Browsers in its internal domain list until they time out; it must
mark these as _authoritative_ entries. Periodically, it MUST check all

local domain entries to see if a server's DomainAnnouncement has timed
out (no DomainAnnouncement received for three times the periodicity the
server gave in the last received DomainAnnouncement) and remove timed-
out servers from its list.

A Master Browser MUST receive and process GetBackupListRequest frames
from clients, returning GetBackupListResponse frames containing a list
of the Backup Servers for its domain.

A Master Browser MUST eventually send BecomeBackup frames (see section
6.9) to one or more Potential Browser servers to increase the number of
Backup Browsers if there are not enough Backup Browsers to handle the
anticipated query load. Note: possible good times for checking for
sufficient backup browsers are after being elected, when timing out
server HostAnnouncements, and when receiving a server's HostAnnouncement
for the first time.

A Master Browser MUST periodically announce itself and the domain it
serves to other (Local) Master Browsers on its subnet, by sending a
DomainAnnouncement frame (see section 6.12) to its subnet.

A Master Browser MUST send a MasterAnnouncement frame (see section 6.11)
to the Domain Master Browser after it is first elected, and periodically
thereafter. This informs the Domain Master Browser of the presence of
all the Master Browsers.

A Master Browser MUST periodically announce itself to all browsers for
its domain on its subnet by sending a LocalMasterAnnouncement frame (see
section 6.10).

A Master Browser MUST receive and process NetServerEnum2 requests from
browser clients, for its own domain and others. If the request is for a
list of servers in its domain, or for a list of domains, it can answer
from its internal lists. Entries in its list marked _authoritative_ MUST

have the SV_TYPE_LOCAL_LIST_ONLY bit set in the returned results; it
must be clear for all other entries. If the request is for a list of
servers in a domain different than the one it serves, it sends a
NetServerEnum2 request to the Domain Master Browser for that domain
(which it can in find in its list of domains and their Domain Master
Browsers).

    Note: The list of servers that the Master Browser maintains and
    returns to the Backup Browsers, is limited in size to 64K of
    data. This will limit the number of systems that can be in a
    browse list in a single workgroup or domain to approximately two
    thousand systems.


Leach, Naik                                             [Page 12]

INTERNET-DRAFT    CIFS/E Browser Protocol        January 10, 1997


A Master Browser SHOULD request all servers to register with it by
sending an AnnouncementRequest frame, if, on becoming the Master Browser
by winning an election, its server list is empty. Otherwise, clients
might get an incomplete list of servers until the servers' periodic
registrations fill the server list.

If the Master Browser on a subnet is not the Primary Domain Controller
(PDC), then it is a Local Master Browser.

A Local Master Browser MUST periodically synchronize with the Domain
Master Browser (which is the PDC). This synchronization is performed by
making a NetServerEnum2 request to the Domain Master Browser and merging
the results with its list of servers and domains. An entry from the
Domain Master Browser should be marked "non-local", and must not
overwrite an entry with the same name marked _authoritative_. The Domain

Master Browser is located as specified in Appendix B.

A Master Browser MUST participate in browser elections (see section
6.8).


A Master Browser for a domain "D" MUST, after winning an election,

register the NetBIOS unique name D(1d).



A Master Browser for a domain "D" MUST, after losing an election,

unregister the NetBIOS unique name D(1d), and do so quickly enough that

the winning browser can successfully register it.



A Master Browser MUST, if it receives a HostAnnouncement,
DomainAnnouncement, or LocalMasterAnnouncement frame another system that
claims to be the Master Browser for its domain, demote itself from
Master Browser and force an election. This ensures that there is only
ever one Master Browser in each workgroup or domain.

A Master Browser SHOULD, if it loses an election, become a Backup
Browser (without being told to do so by the new Master Browser). Since
it has more up-to-date information in its lists than a Potential
Browser, it is more efficient to have it be a Backup Browser than to
promote a Potential Browser.


4.4.3.1 Preferred Master Browser

A Preferred Master Browser supports exactly the same protocol elements
as a Potential Browser, except as follows.


Leach, Naik                                             [Page 13]

INTERNET-DRAFT    CIFS/E Browser Protocol        January 10, 1997


A Preferred Master Browser MUST always force an election when it starts
up.

A Preferred Master Browser MUST participate in browser elections (see
section 6.8).


A Preferred Master Browser MUST set the Preferred Master bit in the
RequestElection frame (see section 6.7) to bias the election in its

favor.

A Preferred Master Browser SHOULD, if it loses an election,
automatically become a Backup Browser, without being told to do so by
the Master Browser.

4.4.4 Domain Master Browser

A Domain Master Browser for a domain MUST act as a Local Master Browser

for its subnet. Thus, it acts exactly like a Local Master Browser,

except where required to act differently by this section.



A Domain Master Browser MUST set type SV_TYPE_DOMAIN_MASTER (see section

6.4.1) in its HostAnnouncement until it is ready to shut down. In its

last HostAnnouncement frame before it shuts down, it SHOULD specify a

type of  0.



A Domain Master Browser for a domain MUST receive and process

MasterAnnouncement frames from Local Master Browsers of its domain, and

keep a list of all the Local Master Browsers in its domain.



A Domain Master Browser MUST periodically synchronize with the Local

Master Browsers for its domain. This synchronization is performed by

making a NetServerEnum2 request to each Local Master Browser for its

"authoritative" entries and merging the results into a master list for

the whole domain.


Leach, Naik                                             [Page 14]

INTERNET-DRAFT    CIFS/E Browser Protocol        January 10, 1997




A Domain Master Browser MUST eventually purge an entry from its master

list if:

. it was originally received from a Local Master Browser

. it has not appeared in any list obtained from a Local Master Browser

  for an implementation specific amount of time

. it has not received any MasterAnnouncement or HostAnnouncement for

  the server or domain specified by the entry



A Domain Master Browser MUST set the PDC bit in the RequestElection

frame (see section 6.7) to bias the election in its favor.



A Domain Master Browser MAY be configured with a list of domains for

which it is to support cross-domain browsing. It MUST periodically

discover or validate the name of the Domain Master Browser for each such

domain using the mechanism in appendix B, and add this information to

its list of domains and their Domain Master Browsers.


5. Mailslot Protocol Specification

The only transaction allowed to a mailslot is a mailslot write. Mailslot
writes requests are encapsulated in CIFS TRANSACT SMBs and sent to a

specified NetBIOS name. The following table shows the interpretation of

the TRANSACT SMB parameters for a mailslot transaction:

 Name            Value               Description
 Command         SMB_COM_TRANSACTION
 Name            <name>              STRING name of mail slot to write;
                                     must start with "\MAILSLOT\"
 SetupCount      3                   Always 3 for mailslot writes
 Setup[0]        1                   Command code == write mailslot
 Setup[1]        Ignored
 Setup[2]        Ignored
 TotalDataCount  n                   Size of data in bytes to write to
                                     the mailslot

Leach, Naik                                             [Page 15]

INTERNET-DRAFT    CIFS/E Browser Protocol        January 10, 1997


 Data[ n ]                           The data to write to the mailslot


When it is specified that a mailslot message  is "sent to NetBIOS name X

and mailslot Y" it means that a NetBIOS datagram  (as specified in

section 4.4.2 of [RFC 1002]) is sent whose

. MSG_TYPE is DIRECT_UNIQUE_DATAGRAM if the NetBIOS name is a unique

  name

. MSG_TYPE is DIRECT_GROUP_DATAGRAM if the NetBIOS name is a group name

. SOURCE_NAME field is the NetBIOS name of the sending system

. DESTINATION_NAME is X

. USER_DATA field contains an SMB_COM_TRANSACTION SMB (as specified in

  the CIFS spec) with its fields as specified in the table above.

 (or the equivalent, if the NetBIOS service in use is over a protocol

other than as specified by RFC 1001/1002.)



In order to receive mailslot messages, a system MUST have done a NetBIOS

registration (as per section 5.2 of RFC 1001) of the DESTINATION_NAME to

which the message was sent.



Before sending a mailslot message, the sending system SHOULD have done a

NetBIOS registration of the SOURCE_NAME in the message to be sent.


6. Browser Protocol Specification

As already explained, browser datagrams are also referred to as Browser
frames. What distinguishes one browser frame from another is the opcode

that is carried as the data portion of the Transact SMB, and the NETBIOS
name and mailslot to which the browser frame is sent.  Browser frames

are often referred to by the symbolic name of the opcode that is within

the data portion of the Transact SMB. The following sections describe
the various Browser frames.

Leach, Naik                                             [Page 16]

INTERNET-DRAFT    CIFS/E Browser Protocol        January 10, 1997


6.1 NETBIOS Name Notation

NAME(xx) denotes the ASCII string "NAME," padded with spaces (0x20) to
15 bytes, with a hex xx value in the 16th byte. For example, the
notation FOOBAR(15) indicates a NETBIOS name consisting of the bytes:
    [69,79,79,65,64,82,20,20,20,20,20,20,20,20,20, 15]

Names that are placeholders and that need to be substituted with their
actual values are bracketed within <>. Thus the string <Domain> would
become _Redmond_ if the domain under consideration is named _Redmond_.
Details of the various NETBIOS names used for browsing are described in
Appendix C.

6.2 GetBackupListRequest Browser Frame

The GetBackupListRequest frame is sent by a browser client to any Master
Browser for a domain to allow the client to learn the identities of
Backup Browsers. To get the list of Backup Browsers for domain "D" from

the Local Master Browser for that domain,  the GetBackupListRequest

browser frame is sent to to NETBIOS unique name D(1d) and mailslot

_\MAILSLOT\MSBROWSE_. To get the list of Backup Browsers for domain "D"

from the Domain Master Browser for that domain,  the

GetBackupListRequest browser frame is sent to to NETBIOS unique name

D(1b) and mailslot _\MAILSLOT\MSBROWSE_. The definition of the

GetBackupListRequest frame is:

    struct {
        unsigned char OpCode;
        unsigned short Token;
    }

where :

OpCode identifies this structure as a request to return a list of Backup
servers. Opcode is defined as GetBackupListRequest and has a value of
decimal 9.

Token is a handle of meaning only to the client issuing the browser
frame. The Local Master Browser will return this token unmodified in the
response. The client should use this to distinguish replies to multiple
outstanding GetBackupList requests. This implies that every
GetBackupListRequest should have an unique handle, at least within the
outstanding lifetime of a request.

The expected response is a GetBackupListResponse frame (see next
section).


Leach, Naik                                             [Page 17]

INTERNET-DRAFT    CIFS/E Browser Protocol        January 10, 1997


6.3 GetBackupListResponse Browser Frame

The GetBackupListResponse frame is sent by a Master Browser in response
to a GetBackupListRequest frame. The GetBackupListResponse frame is sent

to the NETBIOS unique name in the SOURCE_NAME of the mailslot message

containing the GetBackupListRequest and mailslot \MAILSLOT\LANMAN. Note:

this name is not part of the body of the request and on many systems the

Master Browser will need to obtain this name from the NetBIOS service.

The definition of the GetBackupListResponse frame is:

    struct {
        unsigned char   OpCode;
        unsigned short  BackupServerCount;
        unsigned short  Token;
        unsigned char   BackupServerList[][]
    }
where:
     Opcode __Identifies this structure as a backup list.

     BackupServerCount __Specifies the number of backup servers
         that follow this list.

     Token __Is returned unmodified to the client. This is used by
         the client to associate an incoming BackupListResponse
         with its BackupListRequest.

     BackupServerList __ASCII backup servers. Each server name is
         null terminated and up to 16 bytes in length.


6.4 The NetServerEnum2 RAP Service

The NetServerEnum2 RAP service lists all computers of the specified type
or types that are visible in the specified domains. It may also
enumerate domains.

The following definition uses the notation and terminology defined in
the CIFS Remote Administration Protocol specification, which is required
in order to make it well-defined. The definition is:











Leach, Naik                                             [Page 18]

INTERNET-DRAFT    CIFS/E Browser Protocol        January 10, 1997


    unsigned short NetServerEnum2 (
        unsigned short  sLevel,
        RCVBUF      pbBuffer,
        RCVBUFLEN   cbBuffer,
        ENTCOUNT        pcEntriesRead,
        unsigned short *pcTotalAvail,
        unsigned long  fServerType,
        char        *pszDomain,
    );

where:

   sLevel specifies the level of detail (0 or 1) requested.

   pbBuffer points to the buffer to receive the returned data. If the
   function is successful, the buffer contains a sequence of
   server_info_x structures, where x is 0 or 1, depending on the
   level of detail requested.

   cbBuffer specifies the size, in bytes, of the buffer pointed to by
   the pbBuffer parameter.

   pcEntriesRead points to a 16 bit variable that receives a count of
   the number of servers enumerated in the buffer. This count is
   valid only if NetServerEnum2 returns the NERR_Success or
   ERROR_MORE_DATA values.

   pcTotal Avail points to a 16 bit variable that receives a count of
   the total number of available entries. This count is valid only if
   NetServerEnum2 returns the NERR_Success or ERROR_MORE_DATA values.

    fServerType specifies the type or types of computers to enumerate.
    Computers that match at least one of the specified types are
    returned in the buffer. Possible values are defined in the request
    parameters section.

   pszDomain points to a null-terminated string that contains the
   name of the workgroup in which to enumerate computers of the
   specified type or types. If the pszDomain parameter is a null
   string or a null pointer, servers are enumerated for the current
   domain of the computer.

6.4.1 Transaction Request Parameters section

The Transaction request parameters section in this instance contains:
. The 16 bit function number for NetServerEnum2 which is 104.
. The parameter descriptor string which is "WrLehDz".
. The data descriptor string for the (returned) data which is "B16" for
  level detail 0 or "B16BBDz" for level detail 1.
. The actual parameters as described by the parameter descriptor
  string.

The parameters are:


Leach, Naik                                             [Page 19]

INTERNET-DRAFT    CIFS/E Browser Protocol        January 10, 1997


. A 16 bit integer with a value of 0 or 1 (corresponding to the "W" in
  the parameter descriptor string. This represents the level of detail
  the server is expected to return
. A 16 bit integer that contains the size of the receive buffer.
. A 32 bit integer that represents the type of servers the function
  should enumerate. The possible values may be any of the following or
  a combination of the following:

SV_TYPE_WORKSTATION        0x00000001 All workstations
SV_TYPE_SERVER             0x00000002 All servers
SV_TYPE_SQLSERVER          0x00000004 Any server running with SQL
                                      server
SV_TYPE_DOMAIN_CTRL        0x00000008 Primary domain controller
SV_TYPE_DOMAIN_BAKCTRL     0x00000010 Backup domain controller
SV_TYPE_TIME_SOURCE        0x00000020 Server running the timesource
                                      service
SV_TYPE_AFP                0x00000040 Apple File Protocol servers
SV_TYPE_NOVELL             0x00000080 Novell servers
SV_TYPE_DOMAIN_MEMBER      0x00000100 Domain Member
SV_TYPE_PRINTQ_SERVER      0x00000200 Server sharing print queue
SV_TYPE_DIALIN_SERVER      0x00000400 Server running dialin service.
SV_TYPE_XENIX_SERVER       0x00000800 Xenix server
SV_TYPE_NT                 0x00001000 NT server
SV_TYPE_WFW                0x00002000 Server running Windows for
                                      Workgroups
SV_TYPE_SERVER_NT          0x00008000 Windows NT non DC server
SV_TYPE_POTENTIAL_BROWSER  0x00010000 Server that can run the browser
                                      service
SV_TYPE_BACKUP_BROWSER     0x00020000 Backup browser server
SV_TYPE_MASTER_BROWSER     0x00040000 Master browser server
SV_TYPE_DOMAIN_MASTER      0x00080000 Domain Master Browser server
SV_TYPE_LOCAL_LIST_ONLY    0x40000000 Enumerate only

                                      entries marked "local"local

                                      entries (marked

                                      "authoritative"). This is

                                      meaningful only for the

                                      NetServerEnum2 request and

                                      should be ignored within the

                                      NetServerEnum2 response.


SV_TYPE_DOMAIN_ENUM        0x80000000 Enumerate Domains. The pszDomain
                                      parameter must be NULL.

. A null terminated ASCII string representing the pszDomain parameter
  described above


Leach, Naik                                             [Page 20]

INTERNET-DRAFT    CIFS/E Browser Protocol        January 10, 1997


6.4.2 Transaction Request Data section

There is no data or auxiliary data to send as part of the request.

6.4.3 Transaction Response Parameters section

The transaction response parameters section consists of:
. A 16 bit word indicating the return status. The possible values are:

Code                   Value  Description
NERR_Success           0      No errors encountered
ERROR_MORE_DATA        234    Additional data is available
NERR_ServerNotStarted  2114   The RAP service on the remote computer
                              is not running
NERR_BadTransactConfig 2141   The server is not configured for
                              transactions, IPC$ is not shared

. A 16 bit "converter" word.
. A 16 bit number representing the number of entries returned.
. A 16 bit number representing the total number of available entries.
  If the supplied buffer is large enough, this will equal the number of
  entries returned.

6.4.4 Transaction Response Data section

The return data section consists of a number of SHARE_INFO_1 structures.
The number of such structures present is determined by the third entry
(described above) in the return parameters section.

At level detail 0, the Transaction response data section contains a
number of SERVER_INFO_0 data structure. The number of such structures is
equal to the 16 bit number returned by the server in the third parameter
in the Transaction response parameter section. The SERVER_INFO_0 data
structure is defined as:

    struct SERVER_INFO_0 {
        char        sv0_name[16];
    };

 where:

   sv0_name is a null-terminated string that specifies the name of a
   computer or domain .

At level detail 1, the Transaction response data section contains a
number of SERVER_INFO_1 data structure. The number of such structures is
equal to the 16 bit number returned by the server in the third parameter
in the Transaction response parameter section. The SERVER_INFO_1 data
structure is defined as:






Leach, Naik                                             [Page 21]

INTERNET-DRAFT    CIFS/E Browser Protocol        January 10, 1997


    struct SERVER_INFO_1 {
        char            sv1_name[16];
        char            sv1_version_major;
        char            sv1_version_minor;
        unsigned long   sv1_type;
        char        *sv1_comment_or_master_browser;
    };

   sv1_name contains a null-terminated string that specifies the name
   of a computer, or a domain name if SV_TYPE_DOMAIN_ENUM is set in
   sv1_type.

   sv1_version_major whatever was specified in the HostAnnouncement
   or DomainAnnouncement frame with which the entry was registered.

   sv1_version_minor whatever was specified in the HostAnnouncement
   or DomainAnnouncement frame with which the entry was registered.

   sv1_type specifies the type of software the computer is running.
   The member can be one or a combination of the values defined above
   in the Transaction request parameters section for fServerType.


   sv1_comment_or_master_browser points to a null-terminated string. If
   the sv1_type indicates that the entry is for a domain, this
   specifies the name of server running the domain master browser;
   otherwise, it specifies a comment describing the server. The comment
   can be a null string or the pointer may be a null pointer.

   In case there are multiple SERVER_INFO_1 data structures to
   return, the server may put all these fixed length structures in
   the return buffer, leave some space and then put all the variable
   length data (the actual value of the sv1_comment strings) at the
   end of the buffer.

There is no auxiliary data to receive.

6.5 HostAnnouncement Browser Frame

To advertise its presence, i.e. to publish itself as being available, a
non-browser server sends a HostAnnouncement browser frame. If the server
is a member of domain "D", this frame is sent to the NETBIOS unique name
D(1d) and mailslot _\MAILSLOT\MSBROWSE_. The definition of  the
HostAnnouncement frame is:











Leach, Naik                                             [Page 22]

INTERNET-DRAFT    CIFS/E Browser Protocol        January 10, 1997


    struct {
        unsigned char   Opcode;
        unsigned char   UpdateCount;
        unsigned long   Periodicity;
        unsigned char   ServerName[];
        unsigned char   VersionMajor;
        unsigned char   VersionMinor;
        unsigned long   Type;
        unsigned long   Signature;
        unsigned char   Comment[];
    }

where:
     Opcode __Identifies this structure as a browser server
         announcement and is defined as HostAnnouncement with a
         value of decimal 1.

     UpdateCount _ must be sent as zero and ignored on receipt.

     Periodicity __The announcement frequency of the server (in
         milliseconds). The server will be removed from the browse

         list if it has not been heard from in 3X its announcement
         frequency. In no case will the server be removed from the
         browse list before the period 3X has elapsed. Actual
         implementations may take more than 3X to actually remove
         the server from the browse list.

     ServerName __Null terminated ASCII server name (up to 16 bytes
         in length). This name SHOULD be registered with NetBIOS by

         the server offering the services specified in the Type

         field.


     VersionMajor __The major version number of the OS the server
         is running. it will be returned by NetServerEnum2.

     VersionMinor __The minor version number of the OS the server
         is running. This is entirely informational and does not
         have any significance for the browsing protocol.

     Type __Specifies the type of the server. The server type bits
         are specified in the NetServerEnum2 section.

     Signature __ The browser protocol minor version number in the
         low 8 bits, the browser protocol major version number in
         the next higher 8 bits and the signature 0xaa55 in the
         high 16 bits of this field. Thus, for this version of the
         browser protocol (1.15) this field has the value
         0xaa55010f. This may used to isolate browser servers that
         are running out of revision browser software; otherwise,
         it is ignored.

Leach, Naik                                             [Page 23]

INTERNET-DRAFT    CIFS/E Browser Protocol        January 10, 1997


     Comment __Null terminated ASCII comment for the server.
         Limited to 43 bytes.

When a non-browser server starts up, it announces itself in the manner
described once every minute. The frequency of these statements is
gradually stretched to once every 12 minutes.

Note: older non-browser servers in a domain "D" sent HostAnnouncement
frames to the NETBIOS group name D(00). Non-Browser servers supporting
version 1.15 of the browsing protocol SHOULD NOT use this NETBIOS name,
but for backwards compatibility Master Browsers MAY receive and process
HostAnnouncement frames on this name as described above for D(1d).

6.6 AnnouncementRequest Browser Frame

When a Master Browser starts up and its browse list is empty, it may
force all servers to announce themselves by broadcasting an
AnnouncementRequest frame. If the Master Browser serves domain "D", the
AnnouncementRequest frame is broadcast using the NETBIOS group name
D(00) and mailslot _\MAILSLOT\LANMAN_. The definition of the
AnnouncementRequest frame is:

    struct {
        unsigned char Opcode;
        unsigned char  ResponseComputerName[];
    };

     Opcode __Identifies this structure as an announcement request
         and is defined as AnnounceMent Request with a value of
         decimal 2.

     ResponseComputerName __Specifies the name of the computer to
         send the server announcement to and is up to 16 bytes in
         length. This is ignored . The response to this browser
         frame is a HostAnnouncement browser frame as described
         immediately above. That browser frame does not use this
         parameter at all.

Recipients of this packet should reply by sending an HostAnnouncement
frame as described above. The reply should be sent within a randomly
determined time period that may have a duration of up to 30 seconds. The
random delay ensures that the Master Browser who sent out the packet
does not get flooded with replies, all at the same time.

6.7 RequestElection Browser Frame

To force the election of a new Master Browser for a domain, any browser
client or server can broadcast a RequestElection frame. If the election
is for domain "D", the frame is broadcast using the NETBIOS group name
D(1e) and mailslot _\MAILSLOT\MSBROWSE_. The definition of the
RequestElection frame is:




Leach, Naik                                             [Page 24]

INTERNET-DRAFT    CIFS/E Browser Protocol        January 10, 1997


     struct {
        unsigned char Opcode;
        unsigned char Version;
        unsigned long Criteria;
        unsigned long TimeUp;
        unsigned long MustBeZero;
        unsigned char ServerName[];
     }

    Opcode __Identifies this structure as an election request, and is
        defined as RequestElection, with a value of decimal 8.

    Version __Specifies the version of this election packet. This is a
        constant and always has the value 0x00010f00

    Criteria __Specifies the election criteria of the sender. Produced
        by OR'ing together the Version and the following:

    OS info:
        Windows for Workgroups & Windows 95:    0x00000000
        Windows NT:                     0x01000000
        Windows NT Server:                  0x02000000
    Role:
        PDC:                                0x00000080
        Preferred Master:                   0x00000008
        Running Master:                 0x00000004
        Backup Browser which was
        recently a Master Browser:          0x00000002
        Running Backup Browser:             0x00000001
        Using NBNS for NETBIOS:             0x00000020

    The following masks can be used to isolate parts of the Criteria:

    Operating System Type Mask              0xFF000000
    Election Protocol Version Mask:         0x00FFFF00
    Per version criteria mask:              0x000000FF


    TimeUp __The number of seconds that the server has been up.

    MustBeZero__Must be zero.

    ServerName __Null terminated ASCII server name (up to 16 bytes in
        length).


6.8 Browser Elections

All browsers for a domain "D" MUST listen for RequestElection frames on
the group name D(1e) and mailslot _\MAILSLOT\MSBROWSE_.

Elections proceed in rounds. A round is initiated when a RequestElection
frame is sent. When a Browser receives a RequestElection frame, it
determines if it has won the round using the following rules:

Leach, Naik                                             [Page 25]

INTERNET-DRAFT    CIFS/E Browser Protocol        January 10, 1997



        If it has lost an election in the last several seconds, it loses
        If its election Version is greater than the senders election
        Version, it wins
        Else if its election Criteria (including the election version)
        is greater than the senders Criteria, it wins
        Else if it has been up longer than the sender, it wins
        Else if its name is lexically lower than the sender's name, it
        wins
                (I.e., at this point, a sever named A will become Master
                Browser over a server named X)

(Note that many browsers which receive a RequestElection frame may win a
round.)

Each time it wins a round,  a browser sends out a RequestElection frame,
after a delay based on the browser's current role in the domain:
. Master Browsers and Domain Master Browsers delay for 100 ms.
. Backup Browsers delay for an amount randomly chosen from the interval
  200-600 ms.
. All other browsers delay for an amount randomly chosen from the
  interval 800-3000 ms.

If a browser loses a round it drops out of the election by ignoring
RequestElection frames until it receives a LocalMasterAnnouncement frame
that tells which system is the new Master Browser.

If a browser wins 4 rounds in a row, it becomes the Master Browser.

6.9 BecomeBackup Browser Frame

If a Local Master Browser for a domain "D" wants to promote a Potential
Browser to Backup Browser, it broadcasts a  BecomeBackup frame using the
NETBIOS group name D(1e) and the _\MAILSLOT\MSBROWSE_ mailslot. The
definition of the BecomeBackup frame is:

    struct {
        unsigned char Opcode;
        unsigned char BrowserToPromote[];
    }

     Opcode __ Identifies this structure as a browser server
         announcement, is defined as BecomeBackup, with a value of
         decimal 11

     BrowserToPromote __Specifies the name of the browser server to
         be promoted to backup. Maximum of 16 bytes in length.


6.10 LocalMasterAnnouncement Browser Frame

A Local Master Browser for a domain announces itself to all the other
browsers in its domain that are on its subnet using the
LocalMasterAnnouncement frame. If the Local Master Browser serves domain

Leach, Naik                                             [Page 26]

INTERNET-DRAFT    CIFS/E Browser Protocol        January 10, 1997


"D", the LocalMasterAnnouncement frame is broadcast using the NETBIOS
group name D(1e) and the mailslot _\MAILSLOT\MSBROWSE_. The definition
of the LocalMasterAnnouncement frame is:

    struct {
        unsigned char Opcode;
        unsigned char UpdateCount;
        unsigned long Periodicity;
        unsigned char ServerName[];
        unsigned char VersionMajor;
        unsigned char VersionMinor;
        unsigned long Type;
        unsigned long Signature;
        unsigned char Comment[];
    }

where:
     Opcode __Identifies this structure as a browser server
         announcement and is defined as LocalMasterAnnouncement
         with a value of decimal 15.

     UpdateCount _ must be sent as zero and ignored on receipt.

     Periodicity __The announcement frequency of the browser (in
         milliseconds). The browser will be removed from the browse

         list if it has not been heard from in 3X its announcement
         frequency. In no case will the server be removed from the
         browse list before the period 3X has elapsed. Actual
         implementations may take more than 3X to remove the server
         from the browse list.

     ServerName __Null terminated ASCII server name (up to 16 bytes
         in length).

     VersionMajor __The major version of the OS the server is
         running. This value is informational and irrelevant to the
         browsing protocol.

     VersionMinor __The minor version of the OS the server is
         running. This value is informational and irrelevant to the
         browsing protocol.

     Type __Specifies the type of the browser. The type bits are
         specified in the description of NetServerEnum2.

     Signature __ The browser protocol minor version number in the
         low 8 bits, the browser protocol major version number in
         the next higher 8 bits and the signature 0xaa55 in the
         high 16 bits of this field. This may used to isolate
         browser servers that are running out of revision browser
         software; otherwise, it is ignored. Thus, for this version
         of the browser protocol (1.15) this field has the value
         0xaa55010f.

Leach, Naik                                             [Page 27]

INTERNET-DRAFT    CIFS/E Browser Protocol        January 10, 1997


     Comment __Null terminated ASCII comment for the browser.
         Limited to 43 bytes.

Local Master Browsers do not need to send HostAnnouncement frames; the
LocalMasterAnnouncement accomplishes that function.

6.11 MasterAnnouncement browser Frame

The MasterAnnouncement frame is sent by a Local Master Browser to the
Domain Master Browser, which runs on the PDC. If the name of the PDC is
"PDCName", then the MasterAnnouncement frame is sent to the NETBIOS
unique name PDCName(00) and mailslot _\MAILSLOT\MSBROWSE_. Appendix B
describes how to determine the name of the Primary Domain Controller.
The definition of the MasterAnnouncement frame is::

    struct {
        unsigned char   Opcode;
        unsigned char  MasterBrowserServerName[];
    };

    Opcode __Identifies this structure as a master browser server
        announcement and is defined as MasterAnnouncement with a value
        of decimal 13.

    MasterBrowserServerName __Specifies the name of the master browser
        server (up to 16 bytes in length).


6.12 DomainAnnouncement Browser Frame

Master Browsers (including Local Master Browsers and Domain Master
Browsers) announce the domain they serve to any other Master Browsers on
their subnet by broadcasting a DomainAnnouncement frame using the
NETBIOS group name _(01)(02)__MSBROWSE__(02)(01)_ and mailslot

_\MAILSLOT\MSBROWSE_. The definition of the DomainAnnouncement frame is:

    struct {
        unsigned char   Opcode;
        unsigned char UpdateCount;
        unsigned long Periodicity;
        unsigned char DomainName[];
        unsigned char VersionMajor;
        unsigned char VersionMinor;
        unsigned long Type;
        unsigned long Signature;
        unsigned char MasterBrowserName[];
    }

where:
     Opcode __Identifies this structure as a browser server
         announcement and is defined as DomainAnnouncement with a
         value of decimal 12.


Leach, Naik                                             [Page 28]

INTERNET-DRAFT    CIFS/E Browser Protocol        January 10, 1997


     UpdateCount _ must be sent as zero and ignored on receipt.

     Periodicity __The announcement frequency of the domain (in
         milliseconds). The domain will be removed from the browse

         list if it has not been heard from in 3X its announcement
         frequency. In no case will the domain be removed from the
         browse list before the period 3X has elapsed. Actual
         implementations may take more than 3X to actually remove
         the domain from the browse list.

     DomainName __Null terminated ASCII server name (up to 16 bytes
         in length).

     VersionMajor __The major version of the OS the server is
         running. This value is informational and irrelevant to the
         browsing protocol.

     VersionMinor __The minor version of the OS the server is
         running. This value is informational and irrelevant to the
         browsing protocol.

     Type __Specifies the type of the server. The server type bits
         are specified in the previous section.

     Signature __ The browser protocol minor version number in the
         low 8 bits, the browser protocol major version number in
         the next higher 8 bits and the signature 0xaa55 in the
         high 16 bits of this field. This may used to isolate
         browser servers that are running out of revision browser
         software; otherwise, it is ignored. Thus, for this version
         of the browser protocol (1.15) this field has the value
         0xaa55010f.

     MasterBrowserName __Null terminated ASCII string containing
         the name of the master browser server for this domain.


7. References
[CIFS 96}       I. Heizer, P. Leach, D. Perry, "Common Internet Files
        System Protocol (CIFS/1.0)", Internet-Draft, <draft-heizer-cifs-
        v1-spec-00.txt>,June 30, 1996 . (Work in Progress)
[RFC 1001]      K. Auerbach, A. Aggarwal, "Protocol Standard for a
        NETBIOS Service on a TCP/UDP Transport: Concepts and Methods",
        RFC 1001, Epilogue Technology, March 1987.
[Bradner 96]    S. Bradner, ""Key words for use in RFCs to Indicate
        Requirement Levels", Internet-Draft, <draft-bradner-key-words-
        02.txt>, August 1996 (Work in Progress)

8. Author's Addresses
Paul Leach
Dilip Naik
Microsoft
1 Microsoft Way

Leach, Naik                                             [Page 29]

INTERNET-DRAFT    CIFS/E Browser Protocol        January 10, 1997


Redmond, WA 98052
 paulle@microsoft.com
v-dilipn@microsoft.com

9. Appendix A - Multi-net considerations

To begin with, let's clearly define what is meant by multiple networks
here. A computer can be running one or more network protocols on a
single network adapter card such as IP and IPX. Each of these is
considered to be a _network_ for the purposes of this paragraph. A
computer could also have multiple network adapter cards, and there could
be different protocols running on the different adapter cards, or even
the same protocol(s) on all of the adapter cards. So, more precisely, a
network here means a transport protocol per adapter card. A computer
with 2 physical network cards, running 2 different transport protocols
on each network card, would have 4 logical networks.

Browsers need to remember which logical network a server is located on.
When a client queries a browser for a list of servers, the browser
server needs to return a list of servers that are on the same logical
network on which the client query arrived at the browser server. So a
client that sends a browser frame using say IP will only be returned
information about servers that sent announcements using IP.
To summarize, browser servers need to understand the concept of logical
networks and track server announcements as well as client queries on a
per logical network basis.

10. Appendix B - Primary Domain Controller Location Protocol

This appendix details how a client goes about locating a Primary Domain
Controller (PDC). The process is rather involved, because different
versions of the PDC have used different versions of the protocol, and
hence a client that does not know what protocol is supported by its PDC
has to try them all.

A Primary Domain Controller (PDC) for a domain "D" is located by sending
a mailslot message containing a NETLOGON_QUERY frame to a NETBIOS name
and mailslot "\NET\NETLOGON" and then waiting for a reply mailslot
message, which will be sent to the mailslot name specified by the client
in the NETLOGON_QUERY structure., and which will contain a
NETLOGON_RESPONSE structure. If there is no response after a delay, the
message may be retransmitted. The delay MUST be at least twice the
expected service time, and the delay should be doubled after each time-
out.

If a reply is received, the name of the PDC SHOULD be cached for future
use, so as time minimize network traffic. If no reply is received after
several retransmissions, the PDC may be declared to be unreachable, and
no further attempt to locate it should be made for a while (exactly how
long depends on the expected recovery time for a PDC and/or for the
network; typically a minute or so, but should be increased after each
failure).



Leach, Naik                                             [Page 30]

INTERNET-DRAFT    CIFS/E Browser Protocol        January 10, 1997


The only difference between versions of the protocol is the NETBIOS name
to which the message is sent, as follows:

NETBIOS     name      PDC's OS version
name        type      =============
=========== ========
D(1b)       unique    Windows NT 3.51 or later or compatible
D(1c)       group     Windows NT 3.1 or later or compatible
D(00)       group     all

Clients which are configured to know or are willing to assume what
version of the protocol their PDC is running may directly use the
appropriate NETBIOS name for that version. Otherwise, they SHOULD first
attempt D(1b), since it is unicast and creates the least network
traffic; if there is no response, then they SHOULD try the others. They
MAY try them in parallel.

The NETLOGON_QUERY structure is defined as :

    struct NETLOGON_QUERY{
        unsigned char   Opcode;
        char            ComputerName[];
        char            MailslotName[];
        unsigned short  Lm20Token;
    } ;

    Opcode __Identifies this structure as a NETLOGON_QUERY and has a
        value of 0x07.

    ComputerName __Specifies the ASCII name of the computer sending the
        query, and is up to 16 bytes in length. The response is sent to
        NETBIOS unique name <ComputerName>(00).

    MailslotName __Specifies the ASCII name of the mailslot to which the
        response is to be sent, and is up to 256 bytes in length; cannot
        be _\MAILSLOT\LANMAN_ or _\MAILSLOT\MSBROWSE_ or
        "\NET\NETLOGON".

    Lm20Token - has a value of 0xFFFF.


The response mailslot message contains a NETLOGON_RESPONSE data
structure that is defined as the following for non Windows NT clients:

    struct NETLOGON_RESPONSE
    {
        unsigned char   Opcode;
        char            PrimaryDCName[16];
        unsigned short  Lm20Token;
    };

where
    Opcode __Identifies this structure as a NETLOGON_RESPONSE and has a
        value of 0x12.

Leach, Naik                                             [Page 31]

INTERNET-DRAFT    CIFS/E Browser Protocol        January 10, 1997


    PrimaryDCName __Specifies the ASCII name of the Primary Domain
        Controller and is up to 16 bytes in length.

    Lm20Token - has a value of 0xFFFF

Note that this procedure to locate a Primary Domain Controller is
expensive in terms of network traffic. The Microsoft implementations
attempt to alleviate this by caching the PDC Name. Before using the
cached PDC Name, a NetServerEnum2 API is remoted to the PDC and a sanity
check is performed to ensure that the server type returned indicates a
Primary Domain Controller


11. Appendix C - Summary of Special NETBIOS Names

This section details the various NETBIOS names that are involved in
sending and receiving browser frames. The different mailslots involved
in browsing (there are only 3) are described later on when the browser
frames are detailed.


11.1 Registered unique names

<COMPUTER>(00)
     This name is used by all servers and clients to receive second
     class mailslot messages. A system must add this name in order to
     receive mailslot messages. The only browser requests that should
     appear on this name are BecomeBackup, GetBackupListResp,
     MasterAnnouncement, and LocalMasterAnnouncement frames. All other
     datagrams (other than the expected non-browser datagrams) may be
     ignored and an error logged.

<DOMAIN>(1d)
     This name is used to identify a master browser server for domain
     "DOMAIN" on a subnet.  A master browser server adds this name as a
     unique NETBIOS name when it becomes master browser. If the attempt
     to add the name fails, the master browser server assumes that there
     is another master in the domain and will fail to come up. It may
     log an error if the failure occurs more than 3 times in a row (this
     either indicates some form of network misconfiguration or a
     software error). The only requests that should appear on this name
     are GetBackupListRequest and HostAnnouncement requests. All other
     datagrams on this name may be ignored (and an error logged). If
     running a NETBIOS name service (NBNS, such as WINS), this name
     should not be registered with the NBNS.

<DOMAIN>(1b)
     This name is used to identify the Domain Master Browser for domain
     "DOMAIN" (which is also the primary domain controller). It is a
     unique name added only by the primary domain controller. The
     primary domain controller will respond to GetBackupListRequest on
     this name just as it responds to these requests on the <DOMAIN>(1d)
     name.


Leach, Naik                                             [Page 32]

INTERNET-DRAFT    CIFS/E Browser Protocol        January 10, 1997


11.2 Registered group names

(01)(02)__MSBROWSE__(02)(01)
     This name is used by Master Browsers to announce themselves to the
     other Master Browsers on a subnet. It is added as a group name by
     all Master Browser servers. The only broadcasts that should appear
     on this name is DomainAnnouncement requests. All other datagrams
     can be ignored.

<DOMAIN>(00)
     This name is used by clients and servers in domain "DOMAIN" to
     process server announcements. The only requests that should appear
     on this name that the browser is interested in are
     AnnouncementRequest and NETLOGON_QUERY (to locate the PDC) packets.
     All other unidentifiable requests may be ignored (and an error
     logged).

<DOMAIN>(1e)
     This name is used for announcements to browsers for domain "DOMAIN"
     on a subnet. This name is registered by all the browser servers in
     the domain. The only requests that should appear on this name are
     RequestElection and AnnouncementRequest packets. All other
     datagrams may be ignored (and an error logged).

<DOMAIN>(1c)
     This name is registered by Primary Domain Controllers.


12. Appendix D - Browsing Protocol Evolution

This Appendix details how the Microsoft Browser specification evolved
and correlates the evolution to specific Microsoft products.

The first browser implementation was with Lan Manager 1.0. Here, there
were no browser servers as such. Each client acted as its own browser
server. All servers announced themselves by means of datagrams and every
client and server listened for those datagrams. Obviously, the amount of
browser datagram traffic is fairly high and scales extremely poorly with
an increase in the number of servers.

The next major revision in the browser specification was with Windows
For Workgroups. This is where the concept of a browser server was really
introduced.

Windows NT 3.51 expanded upon what Windows For Workgroups built. Windows
NT 3.51 introduced the special NETBIOS name <Domain>(1b) that is
registered with WINS. Windows NT 3.51 also shipped a new redirector for
Windows For Workgroups that could take advantage of this new
<Domain>(1b) name.

In a domain which spans multiple broadcast areas, it may be necessary to
have a configuration file available that can resolve the address of a
browser server. This is because browsers rely on broadcasts for name
resolution, for historical reasons. But these name resolution broadcast

Leach, Naik                                             [Page 33]

INTERNET-DRAFT    CIFS/E Browser Protocol        January 10, 1997


packets are not forwarded by routers that span the multiple broadcast
areas of a domain. One example of such a configuration file is the
LMHOSTS file on Windows NT machines.




















































Leach, Naik                                             [Page 34]


Html markup produced by rfcmarkup 1.111, available from https://tools.ietf.org/tools/rfcmarkup/