Portable Systems Group NT Lan Manager Browser Author: Larry Osterman Revision 1.5, January 27,1993 Printed on: June 5, 1996, 21:06January 26, 1993, 15:01 1. Overview 1 1.1. Acknowledgments 1 1.2. Document Structure 1 1.3. Browser Terms 1 1.4. Browser General Architecture 2 1.5. Client side architecture 2 1.6. Server Side algorithm 2 1.6.1. Startup 2 1.6.2. Shutdown 3 1.6.3. Server roles 3 1.6.3.1. Non-Browser Server 4 1.6.3.2. Browser Server (but not the master) 4 1.6.3.3. Master Browser Server 4 1.6.3.4. Domain Master Browser Server 5 1.7. Election algorithm 5 1.7.1. Forcing an election 5 1.7.2. Election process 5 1.8. Lan Manager (and Windows For Workgroups) interoperability 6 1.9. Multiple Workgroups 6 1.9.1. Windows/NT 6 1.9.2. Windows For Workgroups 7 1.9.3. Lan Manager 7 1.10. Wan considerations 7 1.11. Failure Modes 8 1.11.1. Non browser server Failure 8 1.11.2. Backup Browser server Failure 8 1.11.3. Master Browser server Failure 9 1.11.4. Domain Master Browser server Failure 9 1.11.5. Router (WAN) failure 9 1.12. Multi-Net considerations 9 1.13. Configuration Options 10 1.14. Installation 11 1.14.1. Windows/NT 11 1.14.2. Lan Manager/NT 11 1.15. API Modifications 11 1.15.1. New server types for the NetServerEnum API 11 1.15.2. New server info levels for the NetServerEnum API 12 2. Browser Implementation 13 2.1. Basic Structure 13 2.2. Network Protocols 13 2.2.1. HostAnnouncement 14 2.2.2. DomainAnnouncement 14 2.2.3. RequestAnnouncement 15 2.2.4. BackupListRequest 15 2.2.5. BackupListResponse 16 2.2.6. BecomeBackup 16 2.2.7. RequestElection 17 2.2.8. MasterAnnouncement 18 2.2.9. Network protocol specifics 18 2.2.9.1. Announcement Opcodes 18 2.2.9.2. Special NetBIOS Names 18 2.2.9.3. Mailslot Names 19 2.3. Bowser FsControl's to support the Browser service. 19 3. Revision History 19 1. Overview This document describes the design of the Lan Manager NT and Windows NT browser. As far as this document is concerned, the browser consists of all the components needed to enumerate domains and the servers within a domain . For the purposes of this document, a domain is simply a group of servers that are loosely associated, it should NOT be confused with the security based concept of a domain. 1.1. Acknowledgments This document and the browser architecture described within is derived from the work done by the Windows For Workgroups group for their browser. Much of the original text is from an Email based specification supplied by Eric Rudder, and fleshed out with discussions with Henry Sanders. Additional acknowledgments are due to Dave Thompson and "J" Allard who helped finalize the WAN design. 1.2. Document Structure Section 1 of this specification describes the overall architecture of the browser, as well as the constraints under which the architecture has been defined. Section 2 contains implementation detail about how the browser will be implemented, including structures and protocols. 1.3. Browser Terms For the following discussion, it is useful to define the following terms: NT Domain ** An NT domain is a group of Lan Manager/NT servers that share a common SAM database. An NT workstation may be a part of the domain in that it depends on a SAM database on a server for authentication. Lan Manager servers may be members of the NT domain NT Workgroup ** An NT workgroup consists of a group of independent Windows/NT workstations running the server software. Each workstation maintains its own SAM database. Windows For Workgroups Workgroup ** A Windows For Workgroups workgroup consists of a group of Windows workstations running the Windows For Workgroups server software. Each workstation appears as a share level Lan Manager 1.0 server. Down level Domain ** A down level domain consists of a group of servers running Lan Manager 2.1 and below. Workstations in the down level domain receive server announcements via multicast datagrams. Wide Area Network (WAN)** A Wide Area Network is a network that is fragmented by one or more routers. Broadcast datagrams will not go to all the computers in a domain that spans a router, but will only go the machines on the same sub-net as the computer originating the datagram. Local Subnet** The Local Subnet for a machine is the portion of the network that is directly accessible from a machine. Broadcasts will be received by all machines on the same local subnet. In this discussion, the terms workgroup and domain will be used interchangeably 1.4. Browser General Architecture Client workstations remote requests to perform a NetServerEnum to a "browser server." There can be multiple browser servers within a domain, their activities are coordinated by a "master browser server." The master browser server is chosen by election, rather than by static configuration. This centralized architecture reduces both the dependency on (and use of) broadcast datagrams and resources (both CPU and memory) on the client. Any server running the browser service There are five different types of browser server defined: Potential Browser Server ** The vast majority of browser servers running are potential browser servers. A potential browser has the capability of becoming either a backup or master browser server, but by default serves no function in the domain. Backup Browser Server ** Backup browser servers maintain a list of servers retrieved from the master browser server. Clients will remote NetServerEnum APIs to backup browser servers to retrieve a list of servers or domains. Master Browser Servers ** Master browser servers receive server announcements from Windows For Workgroups, NT, and Lan Manager servers, and also return lists of backup browser servers to Windows For Workgroups and NT clients for their local subnet. They will also function as Backup Browser Servers. On a WAN, Master Browser Servers will also contact the PDC for their domain and retrieve the WAN wide list of servers and domains. Preferred Master Browser Servers (PM) ** Any browser server can be configured as a preferred master browser servers. A machine configured as a preferred master browser server functions as a normal backup browser server, but will force a browser election when the browser is started. Preferred master browser servers are given an advantage in elections that will allow them to win elections (all other things being equal). This allows an administrator to configure one (or more) machines as domain master browser servers to allow the administrator to pick a set of machines that will be master browser servers. Primary Domain Controller (PDC) ** The browser service running on the Primary Domain Controller in a Lan Manager domain has a special role, namely that of "Domain Master Browser". Master browsers for each subnet will announce themselves as master browsers to the PDC using a directed datagram that identifies the master by name, and the PDC will remote a NetServerEnum API to that master server to collect its subnet specific list of servers. 1.5. Client side architecture The client side implementation is "simple". When an application issues a NetServerEnum API, the client will remote the API to a "browser server". The client determines the list of browser servers by issuing a "QueryBrowserServers" mailslot request to a well known name based on the name of the domain being queried which is processed by the master browser server for that subnet . The master browser server will return a list of browser servers that are active within the domain. The client stores three names taken from this list for future use. The client will then remote the NetServerEnum to one of these three servers picked at random. If the master browser server cannot be found after three retries, the client issues a "ForceElection" broadcast to the domain which will force the election of a new master browser server. (See the section on elections on page 55). It then returns ERROR_BAD_NETPATH to the application indicating that the master browser cannot be found. On a wide area network (or on a WAN enabled transport (like TCP/IP)), the browser will not always be able to determine the master browser (If, for example, the domain lies on a different subnet from the client). In that case, the client will remote the API to a local browser (either master or backup) which will examine its list of domains for the domain specified and remote the server to the master browser of that domain . This is known as a "double hop". 1.6. Server Side algorithm 1.6.1. Startup On workstation startup, the browser service will look in the registry for the configuration parameter "MaintainServerList". If MaintainServerList has the value of "No", then this workstation will not participate as a browser server. If MaintainServerList has the value of "Yes", then this server becomes a browser server. It attempts to contact the master browser server to get a current browse list. If it cannot find the master, it forces an election, and is a candidate to become the master. If MaintainServerList has the value of "Auto", then the server may or may not become a browser server, depending on the number of browser servers active on the network. "Auto" is the default value, if none is present. A workstation whose MaintainServerList is "Auto" will be told by the master browser if it is to become a backup browser server. In a workgroup, the master server determines this by the following simple metric: There is one additional browser server for each 32 servers. For example: Number of servers Number of Non Master Browser Servers Number of Masters 1 0 1 2 1 1 3-31 1 1 32 2 1 17-63 2 1 64 3 1 This scheme maximizes the chance that if the master goes down, another browser can take it's place with a relatively up to date list. In addition, the load of performing NetServerEnums is distributed, and scales well. In a domain (a workgroup with one or more Windows/NT advanced servers), every advanced server is a browser server (MaintainServerList is set to "Yes"). If there are more than 3 advanced servers in the domain, then no Windows/NT machines will be chosen as backup browser servers, the 3 advanced servers should be able to pick up the entire load. The list of backup browser servers is chosen entirely from the servers on the local subnet, backup browsers from another subnet will not be chosen. If the backup browser cannot locate a master browser, an election will be forced (See page 55 for details on the election algorithm) If MaintainServerList is configured to be either "Yes" or "Auto", then the installer will be add the browser service to the list of services to be automatically started at system boot. 1.6.2. Shutdown If a non master server is shutting down (gracefully), it will send an announcement to the master that it is shutting down. This is done by forcing a server announcement that does not specify the browser service in the list of running services. If a master server is shutting down (gracefully) it will send a "ForceElection" broadcast so that a new master can be chosen. Note that a packet is not sent to remove the domain from other masters' lists; this is simply done via time-out. 1.6.3. Server roles As described above, there are 5 roles that an NT server can take: Non-Browser Server Potential Browser server Backup Browser Server Preferred Master Browser Servers Master Browser Server Domain Master Browser Server, or DM 1.6.3.1. Non-Browser Server All this server does is to announce itself to the master browser server periodically with a directed mailslot write to a well known name. Each server initially announces itself to the master every minute, but as the server stays up for longer and longer periods, it stretches out its announcement period to a maximum of once every 12 minutes. If a server has not been heard from for three announcements, the server is removed from the browse list. Please note that this means that there is a 36 minute delay between when a server goes down and the time that the server is removed from the list of servers. 1.6.3.2. Potential Browser servers. These servers are a superset of the Non-Browser Server. They announce themselves using the same algorithm as the non-browser server. In addition, Potential browser servers also add a well known group name to allow them to participate in browser elections (see page 55), and thus may become either Backup Browser Servers, or Master Browser Servers. 1.6.3.2. Backup Browser Server These servers are a superset of the Potential Browser server. They announce themselves using the same algorithm as the non browser server, and will participate in elections. These servers also call the master every 15 minutes to get a list of servers; this list is cached, and returned to clients who remote a NetServerEnum API to them. They will also retrieve the list of domains from the master browser server at this time. If, in the course of trying to get an updated list the master cannot be found, an election is held (See page 55 for details on the election algorithm). Master browser servers will periodically announce themselves to the backup browser servers with a broadcast to the well known election name, when backup browsers receive this announcement, they will refresh their master browser name with this new information. 1.6.3.3. Preferred Master Browser Server These servers are a superset of the Backup Browser server. They announce themselves using the same algorithm as the non browser server, and will participate in elections. Preferred Master Browser servers exist to allow an administrator to configure a specific server (or set of servers) to always be the master browser server for a workgroup. This is useful in a WAN configuration where a site might want to have a Win/NT only workgroup that is visible to other domains across a WAN (see page 99 for a discussion of WAN issues). When a Preferred Master Browser starts, it forces an election to be is held (See page 55 for details on the election algorithm). Preferred Master Browser servers are given higher priority over other browser servers during the election process to allow them to win the election. A preferred master browser server is identified by setting the configuration value "IsDomainMasterBrowser" to "Yes" in its registry. 1.6.3.4. Master Browser Server The master browser server is a superset of the Backup Browser server. It announces itself to the well known election name (NOTE: This is NOT the same mechanism as normal browser servers use). The master server answers all requests that it receives. When a server registers, and it's MaintainServerList parameter is "Auto", the master can optionally tell it to become a backup browser server by sending a "BecomeBrowserServer" packet. (Again, the metric is one backup browser server every 32 servers.) On becoming the master (by winning an election), if the master's browse list is empty, it can force all servers to register with the master. It does this by broadcasting a "RequestAnnouncement" packet. All servers that receive this must answer randomly within a 30 second time period. (The 30 second range prevents the master from losing replies due to overloading (and prevents the corporate network from being flooded with requests)). Master browser servers also have to announce their domain. This is performed by broadcasting a AnnounceDomain request to a well known name (<01><02>_MSBROWSE_<02><01>). This announcement contains the domain name and the name of the master browser server for the domain. In addition, they will receive these domain announcements and maintain them in their internal browse list. If a master browser servers is not a PDC, then it synchronize with the domain master browser server (PDC). This is performed by periodically (every 15 minutes) remoting a NetServerEnum API to the domain master browser server. In addition, the master browser server will send a directed MasterBrowserAnnouncement datagram to the domain master browser server. This extra level of synchronization guarantees that the master browser server has a complete list of all of the servers in the domain, regardless of which sub-net they are on. If a master browser server receives a server announcement from another computer that claims to be a master browser server, then it will shut itself down and force an election (see page 55). This makes sure that there is only one master browser on a given domain. 1.6.3.5. Domain Master Browser Server (PDC) The PDC of a Windows/NT Advanced Services domain is also known as the domain master browser server. It functions as a normal master browser server (and is given a bias in elections to ensure that it is the master browser server). In addition to the responsibilities of a normal master browser server, the domain master browser server has to process MasterBrowserAnnouncement requests. When the domain master receives one of these requests, it will remote a NetServerEnum API to the server that issued the announcement to collect the servers from that master. It will then merge that list with its current list. This guarantees that the domain master browser server has a complete browse list of all the servers in the domain. When a client remotes a NetServerEnum API to the domain master browser server, the domain master will return ALL the servers in it's browse list. The primary domain controller will also add the well known name DOMAIN(1b) and will process GetBrowserServerList requests on that name. This name serves no purpose for Windows/NT product 1, however will be used when the Windows Internet Name Service (WINS) is in place. 1.7. Election algorithm 1.7.1. Forcing an election When a client wishes to force an election, it broadcasts an election packet to the domain indicating that an election should take place. This packet is crafted in such a manner to guarantee that the client will NOT win the election (since it is not necessarily running the browser service, it is critical that it not be considered a winner of the election). 1.7.2. Election process Browser servers receive election requests on the group name DOMAIN(1e). When a browser server sees any election packet, it examines the packet and compares it with its own election criteria. If the browser server has better criteria then the issuer of the packet, it will issues it's own election packet and enters an "election-in-progress" state. If it does not have better criteria than the requester of the election, it will attempt to determine the new master browser. The criteria for determining that you have won an election is simple. If your election version is greater than the senders election version, you win Else if your election criteria is greater than the senders criteria, you win Else if you have been up longer than the sender, you win Else if the server with the lexically lowest name wins \NOTE: If there are no browser servers of any type running, then browsing not functional until a potential browser server is brought up \ When the browser receives an election packet that indicates that the machine wins, it enters the "RunningElection" state. While in this state, it sends out an election response after a delay based on its current role in the domain. Master browsers delay for 200ms, backup browsers delay for 400ms, and all other browsers delay for 800ms. This delay is present because WfW browsers go deaf for several hundred microseconds after sending an election packet. The election criteria is based on a servers role in the domain and its current state. The defined hierarchy is: OS Type: 0xFF000000 WfW: 0x00000000 Win/NT: 0x01000000 Win/NT Advanced Services: 0x02000000 Election Version: 0x00FFFF00 Per version criteria: 0x000000FF PDC: 0x00000080 Preferred Master: 0x00000008 Running Master: 0x00000004 MaintainServerList Yes: 0x00000002 Running Backup browser: 0x00000001 The browser OR's in all the appropriate election criteria and uses this to determine what the correct election criteria are for this machine. The browser will send up to 4 election packets, if no other machine has responded with an election packet that would win the election after 4 elections have been sent, the machine will be promoted to master. If an election packet is received indicating that another machine would win the election, and the current machine is the master browser, then it will stop being the master browser for the workgroup and fall back to running as a backup browser. 1.8. Lan Manager (and Windows For Workgroups) interoperability LAN Manager, Windows For Workgroups, and Windows/NT Advanced Services domains can co-exist. If a Windows/NT server wishes to be visible to a LAN Manager client, it must set the LMAnnounce parameter to "YES" in the registry. The default value for this parameter is "NO." Setting this parameter to "YES" will cause the server to periodically broadcast Lan Manager compatible server announcements to Lan Manager clients. LAN Manager servers will automatically appear in Windows/NT domains, as long as the domain name matches the domain name of the Windows/NT domain. The master server will simply listen for Lan Manager announcements, and will update its list accordingly. LAN Manager only domains (Lan Manager domains with no WfW or NT workstations) can only be viewed from Windows/NT Advanced Services domains. To support them, the administrator needs to configure the Lan Manager domain as an "OtherDomain" using the network control panel applet. 1.9. Multiple Workgroups 1.9.1. Windows/NT Clients must not only be able to retrieve lists of servers within a domain, but the list of domains as well. Windows/NT will add a new information level to the NetServerEnum API that will allow a client to retrieve a list of domains from the master. On becoming a master, each master browser server will broadcast one "DomainAnnouncement" a minute for the first 5 minutes of the server's lifetime as a master. After that, once every 15 minutes the master will broadcast another domain announcement. The browser master will receive these DomainAnnouncement packets and place the domain specified in its local browse list. If a domain has not announced itself for 3 times the announcement periodicity, it will be removed from the list of domains A master browser server can force domains to announce themselves upon becoming a master. Please note that this will only be done if the masters' domain list is empty . Included in the "DomainAnnouncement" packet is the name of the domain, and the name of the master browser for that domain. Windows/NT master browsers also include the fact that the machine is a Windows/NT machine, and if the running machine is a PDC or is running Windows/NT Advanced Services. 1.9.2. Windows For Workgroups Windows/NT browsing is derived from the Windows for Workgroups browsing architecture, and thus should interoperate transparently, other than as described above. 1.9.3. Lan Manager In order for a Windows/NT or Windows/NT advanced services client to see Lan Manager servers in domains other than the primary domain, the primary domain controller for the domain must be configured with an "OtherDomains" list in its registry. The client NetServerEnum code will use the "double hop" technique to query the master browser (PDC) to retrieve the list of servers for that domain. 1.10. Wan considerations The following two sections discuss how the browser functions in a WAN (routed) environment. There are two sections, one describing the WAN support as provided in Windows/NT product 1, the second describing the WAN support provided for Windows/NT product 1.1 which contains the WINS (Windows Internet Name Service). 1.10.1. Windows/NT Product 1 (WAN name resolution provided by LMHOSTS file). In Windows/NT product 1, name resolution is performed using broadcasts. As a result, the default (B- Node) name resolution cannot resolve names on subnets other than the local subnet. To solve this problem, a special configuration file, the LMHOSTS file has been added. The LMHOSTS file contains a NetBIOS name to IP address mapping for all servers that are not on your local subnet. All Windows/NT Advanced Services PDCs should be configured in the LMHOSTS file for browsing to function correctly. Windows/NT only provides WAN browsing support for the Windows/NT Advanced Services product, it is only available in a domain . Each local subnet functions as an independent browsing entity, each as its own master browser and backup browsers. In order to allow inter-domain browsing (browsing within a domain) to function across a router, we introduce the concept of a Domain Master browser server. The Domain Master (or DM) maintains a WAN-Wide browser list for the servers in the domain and the all of the domains that are accessible by those servers in the domain. In the above picture, the domain specified spans two subnets. Each subnet has its own master browser server, (on Sub Net 1, the master browser server is also the Primary Domain Controller). Every 15 minutes, the master browser for subnet 2 contacts the PDC and retrieves the entire list of servers and domains from the PDC. It will also announce its presence to the PDC. When the PDC receives this announcement, it will contact the master browser to retrieve its list of servers and domains for that subnet. The master browser for subnet 2 will only return its local list of servers and domains to avoid eternally propagating domain information. This design relies on the fact that all broadcasts are no propagated across sub-net boundaries, and thus name claim packets and elections on one sub-net will not be seen on any other sub-net. Thus elections occur on a per sub-net basis, and name claim requests (used to add the unique name for the master browser server) will not propagate across routers. In order to guarantee that the master browser for each subnet can access the PDC, we require that the PDC for each domain exist in the LMHOSTS file on each client. In order to guarantee that the PDC can request the local subnets list from the subnet master browser, the TCP/IP transport (and all other WAN-ish transports) must cache client addresses for some reasonable period of time. Please note that there is a single point of failure in this architecture. If the PDC ever goes down, then workstations will only be able to see the servers and domains on their local sub-net. In addition, the list of domains retrieved will only be browser will only return the domains that are on the sub-nets occupied by the master browser servers in the domain. Windows/NT workgroups cannot span multiple sub-nets, any Windows/NT workgroup that does will function as two separate workgroups. In addition, workgroups will not be able to view other workgroups on subnets other than the local sub- net. Since a client uses a datagram to retrieve the list of backup browser servers for a domain, a client cannot directly determine the name of a backup browser to retrieve the list of servers in a domain if there are no browser servers for the specified domain. To fix this problem, we introduce the concept of a "double hop". If the client is unable to retrieve the list of backup browsers from the master browser for a domain, it will remote the API request to the master browser for its current workgroup. The browser server will look up the domain in its list of domains and re-remote the API to the master browser server that most recently announced the domains existence. 1.10.1.1. What doesn't work with this scheme. Browsing will not work under the following configurations using this scheme: 1. The servers in Windows/NT or Windows For Workgroups workgroups will not be visible by clients on subnets other than the same subnet as the workgroup. There is a work around for this problem if there is a Windows/NT machine on the workgroup however. The administrator for the workgroup can configure one (or more) of the Windows/NT machines as "Configured Master Browsers", and then add those computers to the LMHOSTS file. 2. Subnet with Windows For Workgroups only clients. This unfortunately cannot work, because the Windows For Workgroups browser is not WAN aware. 3. Subnet with Windows/NT workstations (none of which are running the server). This cannot work because in this configuration, there is no server to become the browse master. This is identical to a workgroup with no servers running in it (which really isn't a workgroup).... 4. Subnet with Windows/NT workstations (none of which are running the browser). This cannot work because in this configuration, there is no server to become the browse master. 5. Browsing all workgroups/domains on the WAN. If there is an isolated workgroup on the WAN (i.e. a domain that is on a subnet that has no machines in the current domain), then it will not be visible via domain browsing. In this example, the domain Domain1 (and the servers in Domain1) will not be visible to any of the servers in Domain2 or Domain3. Likewise, Domain2 and Domain3 (and workgroup Workgroup1) will be invisible to the servers in Domain1. 6. Browsing domains on other subnets whose browse master is not in the LMHOSTS file 1.10.2. Windows/NT Product 1.1 (WAN name resolution provided by WINS). In Windows/NT product 1.1, a name resolution service will be added to the Windows/NT base product that will fix most of the configuration problems described above. This product will NOT provide a NetBIOS Datagram Distributor (NBDD), it will only be a NetBIOS Name Server (NBNS). With WINS in place, client workstations can now resolve any and all NetBIOS names that have been registered with the name service. This means that clients can now access remote servers even if they are not in the LMHOSTS file. Since the browsing architecture relies heavily on broadcasts, WINS will have to be configured to ignore all of the special browser names (with the exception of the DOMAIN(1B) name that is added by the PDC). This allows browsing to continue to function as it does in product 1. In order to make inter-domain browsing work fully in a WAN environment, the browser will query the WINS server to retrieve the list of servers that have registered this DOMAIN(1B) and to retrieve server name for this server. This will allow the full list of all Windows/NT Advanced Services domains to be returned, not just the list of domains accessable by machines in the current domain. \NOTE: The mechanism to do this query is still TBD.\ 1.11. Failure Modes It is possible for any of the 3 types of server to fail, and in a WAN configuration, it is possible for either the entire WAN to fail (if the router goes down), or for any of the domain masters to fail. The browser will handle the failure of all of these in the following manner: 1.11.1. Non browser server Failure If a non browser server fails, it will cease announcing itself (since it's crashed, it cannot announce itself). After 3X its current announcement periodicity (between 3 and 24 minutes), the master browser server will remove the server from its browse list. This means that within 60 minutes of a server failure (45 minutes for the master to detect the failure, 15 minutes for all the backups to pick up the list from the master), all the browser servers will know of the workstations failure. 1.11.2. Backup Browser server Failure If a backup browser server fails, it too will eventually be removed from the master browser servers browse list. Any workstations that have been told the name of the failing browser server will fail to contact the failed server, but they will retry the NetServerEnum API to another browser server. If all of their backup servers have failed, the workstation will attempt to get a new browser server list from the master browser server. If that fails, the workstation will force an election. \NOTE: If all of the browser servers in a domain fail simultaneously (if they were all in a single room and power failed to that room), it is possible that browsing will not function for up to half an hour. This would happen if no backup had contacted the master and no client forced an election.\ 1.11.3. Master Browser server Failure When a master browser server fails, backup browser servers will detect the failure within 12 minutes. When this happens, they will force an election to choose a new master browser server. If a workstation performs its first NetServerEnum API between the masters crashing and a backup detecting the failure, it will also force an election. If a master fails and there are no backups to recover, then all browsing will cease on the workgroup. In addition, during the period between the failure of a master browser and the election of a new browser server, it is conceivable that the domain will disappear from the list of domains visible from another domain. 1.11.4. Domain Master Browser server Failure If there is only one domain master (the PDC), then failure of the DM is virtually identical to the failure of a router. Master browser servers will only see those servers on their sub-nets, and thus after a time, the servers that are not on the local sub-net will eventually age from the browse list and disappear 1.11.5. Router (WAN) failure If a router fails, then server can still see all of the servers that they can access on the local sub-net. The master browser servers will fail to connect to the domain master, and thus will not download the browse list from the domain master. Since it continues to collect announcements from the local sub-net these servers will still be visible. 1.12. Multi-Net considerations In order to guarantee that the list of servers returned by the NetServerEnum API is accurate, the browser will maintain all of it's server information on a per network basis . When a client application issues a NetServerEnum API, the NetServerEnum code running on the workstation will enumerate all the serviced networks and remote the NetServerEnum API to a browser server for that particular transport. Similarly, when a browser server receives a NetServerEnum API, it will only return those servers on the same network as the network it received the NetServerEnum transaction from. Some of the implications of this architecture are as follows: o Since RPC purposely hides the transport from the client, this work has to be done via modifications of RpcXlate and XactSrv. This implies that all browser servers will run both of these services. o All the data structures and server information described above (including the list of browser servers returned from the GetBrowseList API) have to be instanced on a per-network basis. o This inherently limits the number of servers and domains returned to approximately 1000, since only 64K of data can be transfered via the RxNetServerEnum api . 1.13. Configuration Options The browser has the following configuration options: Not all options are valid on all machines or configurations. MaintainServerList The MaintainServerList configuration option is only valid on servers. It has three values: Yes This server will always be a browser server. No This server will NEVER be a browser server Auto This server will become a browser server if the master browser for the domain considers it appropriate for the server to be a browser server. The default for this option is "Auto" IsDomainMaster This parameter indicates that the server is to function as an domain master. It has two values: Yes Setting this parameter to "Yes" will cause the server to function as a backup server, and will give the computer a bias when elections are generated. In addition, setting MaintainServerList to "Yes" will cause an election to be generated when the browser starts. No Setting this parameter to "No" has no effect. The default for this parameter is "No" Other browser related configuration options are: From the workstation service: OtherDomains Each workstation can be configured with up to 4 "OtherDomains". OtherDomains are Lan Manager only domains that the workstation is interested in viewing. If an OtherDomain is configured on a primary domain controller, then this domain is provided to all clients. From the server service: LMAnnounce This parameter will cause the server software to announce itself with a Lan Manager compatible server announcement. It has two possible values: Yes Setting this parameter to "Yes" will cause the server to announce itself to Lan Manager workstations. No Setting this parameter to "No" will not generate any Lan Manager broadcasts. The default for this parameter is "No". In addition to these six user visible configuration options, the browser service will store name of the master browser server and the time that it last retrieved a backup browser list.. 1.14. Installation 1.14.1. Windows/NT When Windows/NT is installed, the NCPA will not prompt the user for any configuration options for the browser. It will allow the user to configure the value of the LMAnnounce parameter. In addition, on PDC's, the NCPA will allow the user to select OtherDomains. On Windows/NT machines that have NOT joined a domain, the NCPA will allow the user to configure a machine with the IsDomainMaster. 1.14.2. Lan Manager/NT Lan Manager/NT installation is identical to Windows/NT installation. The browser determines if it is running on a Lan Manager/NT machine and will always run as a backup browser. In addition, if the browser is running on a primary domain controller, it will always force an election when starting (this is to guarantee that the PDC is always the browse master). 1.15. API Modifications The following describes the modifications to the various NetServerEnum protocols in order to support the Windows/NT browser. 1.15.1. New server types for the NetServerEnum API The following server types are defined for the NetServerEnum API: #define SV_TYPE_WORKSTATION 0x00000001 #define SV_TYPE_SERVER 0x00000002 #define SV_TYPE_SQLSERVER 0x00000004 #define SV_TYPE_DOMAIN_CTRL 0x00000008 #define SV_TYPE_DOMAIN_BAKCTRL 0x00000010 #define SV_TYPE_TIME_SOURCE 0x00000020 #define SV_TYPE_AFP 0x00000040 #define SV_TYPE_NOVELL 0x00000080 #define SV_TYPE_DOMAIN_MEMBER 0x00000100 #define SV_TYPE_PRINTQ_SERVER 0x00000200 #define SV_TYPE_DIALIN_SERVER 0x00000400 #define SV_TYPE_XENIX_SERVER 0x00000800 #define SV_TYPE_NT 0x00001000 #define SV_TYPE_POTENTIAL_BROWSER 0x00010000 #define SV_TYPE_BACKUP_BROWSER 0x00020000 #define SV_TYPE_MASTER_BROWSER 0x00040000 #define SV_TYPE_DOMAIN_MASTER 0x00080000 #define SV_TYPE_LOCAL_LIST_ONLY 0x40000000 #define SV_TYPE_DOMAIN_ENUM 0x80000000 The SV*TYPE*POTENTIAL*BROWSER, SV*TYPE*BACKUP*BROWSER, SV*TYPE*MASTER*BROWSER, and SV*TYPE* DOMAIN*MASTER, fields describe the new types of browser servers described above. For Windows For Workgroups compatibility, if value of the servertype parameter to the NetServerEnum API is SV*TYPE*DOMAIN*ENUM, this indicates that the API should return domains instead of servers. In addition, if the bit SV_TYPE_LOCAL_LIST_ONLY is specified, this indicates that the backup browser is only to return the list of servers retrieved from the local subnet. This is used by domain master browser servers to allow the domain master to retrieve the list of servers on each subnet from the master browser for that subnet. From an applications' standpoint, if it issues a NetServerEnum API, with no domain parameter, it will return all of the servers that are running the services specified by the servertype parameter in the workstations primary domain and in the workstations OtherDomains. If you specify a domain parameter, it will return all the servers in the domain specified running the services specified by the servertype parameter. It will do this even if the Windows For Workgroups or NT domain specified is NOT one of your OtherDomains. When you request the list of domains, it will return the list of all Windows For Workgroups workgroups and NT domains. 1.15.2. New server info levels for the NetServerEnum API If a NetServerEnum API is issued with the SV_TYPE_DOMAIN_ENUM flag, then the structure returned is a standard SERVER_INFO_100 and SERVER_INFO_101 structure. When queried at level 101, the sv101_servercomment field contains the name of the master browser server for that domain. This information is used to support the "double hop" logic described above. It appears that info levels 0 and 1 are used to obtain this info, not 100 and 101. The header files I have (lmserver.h) don't show the format of level 0 and 1, but they are certainly different to 100 and 101. level 0 just has the name of the server (16 bytes) and level 1 has the name, the servertype and the comment. 2. Browser Implementation 2.1. Basic Structure The Browser is implemented in two components, a user level service (Browser.Exe) and a kernel level driver (Bowser.Sys). The kernel level component contains all of the relevant network interface code, and the user level service maintains the master browse list, handles remoting of the API, and contains all the code that manages the various roles a browser server can have. As a direct side effect of this architecture, the NetServerEnum API support will be removed from the workstation service and moved into a new service, the browser. This means that the Net View command will not work unless this new service has been started . 2.2. Network Protocols All the protocols described below are layered on top of the existing Lan Manager mailslot protocol. All of the protocols are sent to the special mailslot \MAILSLOT\LANMAN. The data buffer contains the structures described below. The UDP138 datagrams for browsing are actually sent to \MAILSLOT\BROWSE 2.2.1. HostAnnouncement The HostAnnouncement packet is used for Lan Manager compatible announcements. Windows/NT (and Windows For Workgroups) servers will not generate these packets unless the LMAnnounce parameter is set. HostAnnouncement packets are broadcast packets sent to the DOMAIN(00) name. Lan Manager servers in a workgroup or domain will use this announcement packet to support browsing. Windows/NT (and Windows For Workgroups) browser masters will receive these packets and record the server information in their local browser list. typedef struct _HOST_ANNOUNCEMENT { USHORT Opcode; ULONG InstalledServices; UCHAR MajorVersion; UCHAR MinorVersion; USHORT Periodicity; UCHAR ServerName[]; UCHAR ServerComment[]; } HOST_ANNOUNCEMENT, *PHOST_ANNOUNCEMENT; The above format seems wrong. The OpCode in this and other browse packets is one byte. Also the other fields seem to be wrong.This may be better: typedef struct _HOST_ANNOUNCEMENT { UCHAROpcode; UCHAR UpdateCount; ULONG ttl; UCHAR name[16]; UCHAR osmajor; UCHAR osminor; ULONG ServerType; UCHAR comment[]; } HOST_ANNOUNCEMENT, *PHOST_ANNOUNCEMENT; The above format is used for type 1 (host announce), type 12 (domain announce) and type 15 (local master announce) announcements. HOST_ANNOUNCEMENT Structure: Opcode -- Identifies this structure as a browser server announcement. InstalledServices -- Bit mask describing the services running on the server. MajorVersion -- The major version number of the server software. MinorVersion -- The minor version number of the server software. Periodicity -- The announcement frequency of the server (in seconds). The server will be removed from the browse list if it has not been heard from in 3X it's announcement frequency. ServerName -- Null terminated ASCII server name. ServerComment -- Null terminated ASCII server comment (up to 43 bytes in length). 2.2.2. AnnouncePacket The AnnouncePacket is used to "announce" servers and workgroups. When a Windows/NT (and Windows For Workgroups) server announces, it sends a directed AnnouncePacket request to the unique master name for that workgroup (DOMAIN(1D)). When a Windows/NT (and Windows For Workgroups) master browser announces itself, it sends a broadcast to the group election name (DOMAIN(1E)). This announcement packet serves several purposes: 1. The announcement is used to indicate to backup browsers that the master has changed. Backup browsers will notice this packet and will update their saved version of the master browser name. 2. The master browser will place its information in its local browse list. 3. If a browser master receives an announcement packet from another machine that believes that it is the browser master, the master will shut down, discard its local browser list, and force an election. This allows the correct master to be determined. typedef struct _ANNOUNCE_PACKET { USHORT Opcode; UCHAR UpdateCount; ULONG Periodicity; UCHAR ServerName[16]; UCHAR VersionMajor; UCHAR VersionMinor; ULONG Type; ULONG CommentPointer; UCHAR Comment[]; } ANNOUNCE_PACKET, *PANNOUNCE_PACKET; This is what I described above (except for the OpCode). Its used for host announcements (type 1) as well ANNOUNCE_PACKET Structure: Opcode -- Identifies this structure as a browser server announcement. Legal values include: ANNOUNCE_REQUEST Indicates that this is a server announcement. "ANNOUNCE_REQUEST" is type 2, which is used to request an announcement and uses a different structure (shown below). Opcode can actually be 1, 12 or 15 LOCAL_MASTER_ANNOUNCEMENT Indicates that this is a server announcement from a master browser server. DOMAIN_ANNOUNCEMENT Indicates that this is a domain announcement. UpdateCount -- The UpdateCount field is used to indicate that information has been updated in the servers' announcement list. If contents of the browser masters server or domain list has modified, it will increment UpdateCount and announce. This will allow backup browsers to pick up these updates. Periodicity -- The announcement frequency of the server (in seconds). The server will be removed from the browse list if it has not been heard from in 3X it's announcement frequency. this is actually in milliseconds. Almost of of these TTL fields are in milliseconds, as far as I've seen. The specs says seconds in several places. ServerName -- Null terminated OEM ASCII server name. VersionMajor -- The major version of the server. VersionMinor -- The minor version of the server. Type -- Specifies the type of the server. The server type bits are specified in the previous section. CommentPointer -- Unused. Windows/NT servers will place the election version in the low 8 bits of this field, and will put the signature 0xaa55 in the high 8 bits of this field. This is used to isolate browser servers that are running non functional browser software. it puts 0xaa55 in the high 16 bits, not 8 bits (it would be a squeeze otherwise!) Comment -- Null terminated OEM ASCII comment for the server. Limited to 43 bytes. If this is a domain announcement, this contains the OEM ASCII name of the master browser server for this domain. 2.2.3. RequestAnnouncement The announcement request is either broadcast or sent to individual servers to cause them to announce themselves. It should be infrequently used as it tends to flood the network with datagrams. The RequestAnnouncement packet is also use to discover the master browser in a "FindMaster" operation. When a client browser wishes to find the name of the master browser for a domain/workgroup, the browser will issue a RequestAnnouncement as a directed send to the browser master name for the workgroup. The master browser will receive this packet and will generate an AnnouncePacket that will be broadcast to all the browser servers. typedef struct _REQUEST_ANNOUNCEMENT { USHORT Opcode; UCHAR ResponseComputerName[]; } REQUEST_ANNOUNCEMENT, *PREQUEST_ANNOUNCMENT; opcode is 1 byte. There also seems to be an extra byte (flags?) after the opcode. Or maybe this opcode really is 2 bytes? REQUEST_ANNOUNCEMENT Structure: Opcode -- Identifies this structure as an announcement request. ResponseComputerName -- Specifies the name of the computer to send the server announcement to. This is ignored for Windows/NT and Windows for Workgroups browsers. 2.2.4. BackupListRequest The BackupListRequest packet is sent by workstations to retrieve the list of backup servers from the master browser server. typedef struct _BACKUP_LIST_REQUEST { USHORT Opcode; USHORT Token; BACKUP_LIST_REQUEST, *PBACKUP_LIST_REQUEST; as far as I can tell, it should be: typedef struct _BACKUP_LIST_REQUEST { UCHAR Opcode; UCHAR count; ULONG token; BACKUP_LIST_REQUEST, *PBACKUP_LIST_REQUEST; BACKUP_LIST_REQUEST Structure: Opcode -- Identifies this structure as a request to return the backup list. The response will be sent to the computer that requested the list (NOTE: this name is NOT specified in the structure, but has to come from the network request! This requires that all transports supported return the name of the browser) Token -- The token is used to correlate BackupListResponse operations with the BackupListRequest that initiated the request. 2.2.5. BackupListResponse The BackupListResponse structure is sent in response to a BackupListRequest packet sent to a browser server. typedef struct _BACKUP_LIST_RESPONSE { USHORT Opcode; USHORT BackupServerCount; USHORT Token; UCHAR BackupServerList[][]; } BACKUP_LIST_RESPONSE, *PBACKUP_LIST_RESPONSE; I think this should be: typedef struct _BACKUP_LIST_RESPONSE { UCHAR Opcode; UCHAR count; ULONG token; UCHAR BackupServerList[][]; } BACKUP_LIST_RESPONSE, *PBACKUP_LIST_RESPONSE; BACKUP_LIST_RESPONSE Structure: 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 it's BackupListRequest. BackupServerList -- OEM ASCII backup servers. Each server name is null terminated. 2.2.6. BecomeBackup The BecomeBackup structure is sent by a master browser server to a potential backup browser server when it wishes the potential backup server to become a backup server. When a potential backup server (a server with the MaintainServerList parameter set to Auto) initially announces itself to the master, the master may choose to respond with this. The BecomeBackup packet is sent as a broadcast to the election name (DOMAIN(1E)). typedef struct _BECOME_BACKUP { USHORT Opcode; UCHAR BrowserToPromote[]; } BECOME_BACKUP, *PBECOME_BACKUP; I haven't looked into this one yet (samba doesn't send it yet) BECOME_BACKUP Structure: Opcode -- Identifies this structure as a browser server announcement. BrowserToPromote -- Specifies the name of the browser server to be promoted to backup. 2.2.7. RequestElection The RequestElection broadcast is sent to all browsers in a domain within the local sub-net. If the machine requesting the election is not eligible to win the election, it forces its ServerName, Criteria, and TimeUp parameters to make it impossible to win the election. The winner of the election is chosen by the algorithm described on page 55. typedef struct _REQUEST_ELECTION { USHORT Opcode; UCHAR Version; ULONG Criteria; ULONG TimeUp; ULONG MustBeZero; UCHAR ServerName[]; } REQUEST_ELECTION, *PREQUEST_ELECTION This needs a char opcode. Also TimeUp is in milliseconds. REQUEST_ELECTION Structure: Opcode -- Identifies this structure as an election request. Version -- Specifies the version of this election packet. Criteria -- Specifies the election criteria of the client. TimeUp -- The number of seconds that the server has been up. MustBeZero-- Must be zero. ServerName -- Null terminated ASCII server name. 2.2.8. ResetBrowserState The ResetBrowserState is a diagnostic packet that can be used to force a browser master to stop functioning as a browser master. typedef struct _RESET_STATE { USHORT Opcode; UCHAR Options; RESET_STATE, *PRESET_STATE; I don't parse this one yet in samba so I couldn't check it RESET_STATE Structure: Opcode -- Identifies this request as a reset browser state packet. Options -- Specifies the operation to take. Legal values are: RESET_STATE_STOP_MASTER (0x01) This indicates that the master browser should stop functioning as a master. This means that it should remove the master name and the domain announcement name and fall back as a backup browser. RESET_STATE_CLEAR_ALL (0x02) This indicates that browser should clear its browser state. This means that the browser should discard its server list and effectively restart. RESET_STATE_STOP (0x04) This indicates that the browser should stop functioning at all. For security reasons, the NT browser does not support this packet. 2.2.9. MasterAnnouncement The MasterAnnouncement is sent by the master browser on a subnet to the PDC (DomainMaster) browser server. It simply announces the presence of the master on the domain, to allow the PDC to retrieve the local subnets domain list. typedef struct _MASTER_ANNOUNCEMENT { USHORT Opcode; UCHAR MasterBrowserServerName[]; MASTER_ANNOUNCEMENT, *PMASTER_ANNOUNCEMENT; I don't send this one yet, so I can't check it. MASTER_ANNOUNCEMENT Structure: Opcode -- Identifies this structure as a master browser server announcement. MasterBrowserServerName -- Specifies the name of the master browser server. 2.2.10. Network protocol specifics The following are additional details regarding the network protocols. 2.2.10.1. Announcement Opcodes #define HostAnnouncement 1 #define AnnouncementRequest 2 #define Election 8 #define GetBackupListReq 9 #define GetBackupListResp 10 #define BecomeBackup 11 #define DomainAnnouncment 12 #define MasterAnnouncement 13 #define ResetBrowserState 14 #define LocalMasterAnnouncement 15 2.2.10.2. Special NetBIOS Names For compatibility reasons, this browsing architecture is heavily tied to several special NetBIOS names. For this section, the following conventions are used: NAME(xx) indicates the ASCII string "NAME," padded with spaces (0x20) to 15 bytes, with a hex xx value in the 16th byte. Thus the traditional MS-NET server name would be described as "SERVER(20)" indicates a hex value of xx. Thus the name "FOOBAR" indicates a NetBIOS name consisting of the bytes: [69,79,79,65,64,82,xx,00,00,00,00,00,00,00,00,00] In particular, the following names are used: <01><02>**MSBROWSE**<02><01> This name is used for domain announcements on a local sub-net. It is added as a group name by all masters browser servers. The only broadcasts that should appear on this name are WinBALLWorkgroupAnnouncement and DomainAnnouncement requests. All other datagrams will be ignored. DOMAIN(00) This name is used by Lan Manager workstations and servers to process server announcements. Windows/NT and Windows For Workgroups servers ignore this name unless the LMAnnounce configuration parameter is set to Yes. The only requests that should appear on this name that the browser is interested in are HostAnnouncement and AnnouncementRequest packets. All other unidentifiable requests will be ignored (and an error logged). DOMAIN(1d) This name is used to identify a master browser server. The master browser server adds this name as a unique NetBIOS name when it comes up. If the attempt to add the name fails, the master server assumes that there is another master in the domain and will fail to come up. It will log an error if the failure occurs more than 3 times in a row (this either indicates some form of network mis-configuration or a software error). The only requests that should appear on this name are GetBackupListRequest requests. All other datagrams will be ignored (and an error logged). DOMAIN(1b) This name is used to identify 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. The DOMAIN(1b) name is registered with WINS (the Windows Internet Naming Service), and thus workstations on an isolated sub-net will be able to browse even if there are no servers running on this subnet. In addition, Windows For Workgroups clients will be able to use this name to allow them to retrieve the backup list over a wide area network. DOMAIN(1e) This name is used for all domain wide announcements in a Windows For Workgroups/Windows|NT domain. This name is added by all the browser servers in the domain. The only requests that should appear on this name are Election and AnnouncementRequest packets. All other datagrams will be ignored (and an error logged). COMPUTER(00) This name is used by a Lan Manager workstation to receive second class mailslot requests. All workstations must add this name in order to receive mailslots. The only browser requests that should appear on this name are BecomeBackup, GetBackupListResp, MasterAnnouncement, and DomainMasterAnnouncement requests. All other datagrams (other than the expected non browser datagrams) will be ignored and an error logged. 2.2.10.3. Mailslot Names All the browser messages destined for the COMPUTER(00) name as well as all the messages for the DOMAIN(00) name are sent to the special mailslot name \MAILSLOT\LANMAN. All other browser messages are sent to the mailslot \MAILSLOT\MSBROWSE. They seems ot be all sent to \MAILSLOT\BROWSE. 2.3. Bowser FsControl's to support the Browser service. 3. Revision History Original Draft, Revision 0.1, February 21, 1992 Major changes, Revision 0.2, April 2, 1992 Still more changes, including an update to the current implementation, Revision 1.5, January 27, 1992 notes added by Andrew.Tridgell@anu.edu.au 15th November 95 In WinBALL, a Domain is called a "workgroup". The well known name is the domain name padded with spaces to 16 bytes with an <07> as the 16th byte (represented here as DOMAIN<1d>). The list of domains also includes the name of the master browser for each domain. This information is included as a part of the domain announcement. This can occur when a potential browser server is promoted to master. It is important to note that it there need only be one Windows/NT Advanced Services server in the domain to allow browsing to span the domain, a sub-net that has only Windows/NT servers on it will be able to browse the entire contents of the domain. For the purposes of this discussion, "per network" should be considered "per physical net card/transport". This means that if the client has bound to \Device\Nbf\ElnkII and \Device\TcpIp\ElnkII, there will be two copies of all of the relevant browser information. This includes information kept in the registry. RxNetServerEnum is the RpcXlate stub for the NetServerEnum API. The NET command should be modified to offer to start the browser service if the user does a NET VIEW without having the browser started. Microsoft Corporation Company Confidential Microsoft Corporation Company Confidential Document Name i NT Lan Manager Browser iiiiiiii Microsoft Corporation Company Confidential Microsoft Corporation Company Confidential Windows/NT Browser Specification Page 2625251