Edits in progress.

[Samba/ekacnet.git] / docs / docbook / projdoc / Browsing-Quickguide.sgml

<chapter id="Browsing-Quick">
<chapterinfo>
        &author.jht;
        <pubdate>July 5, 1998</pubdate>
        <pubdate>Updated: March 15, 2003</pubdate>
</chapterinfo>

<title>Quick Cross Subnet Browsing / Cross Workgroup Browsing guide</title>

<para>
This document should be read in conjunction with Browsing and may
be taken as the fast track guide to implementing browsing across subnets
and / or across workgroups (or domains). WINS is the best tool for resolution
of NetBIOS names to IP addesses. WINS is NOT involved in browse list handling
except by way of name to address mapping.
</para>

<note><para>
MS Windows 2000 and later can be configured to operate with NO NetBIOS 
over TCP/IP. Samba-3 and later also supports this mode of operation.
</para></note>


<sect1>
<title>Discussion</title>

<para>
Firstly, all MS Windows networking is based on SMB (Server Message
Block) based messaging. SMB messaging may be implemented using NetBIOS or 
without NetBIOS. Samba implements NetBIOS by encapsulating it over TCP/IP.
MS Windows products can do likewise. NetBIOS based networking uses broadcast
messaging to affect browse list management. When running NetBIOS over
TCP/IP this uses UDP based messaging. UDP messages can be broadcast or unicast.
</para>

<para>
Normally, only unicast UDP messaging can be forwarded by routers. The
<command>remote announce</command>
parameter to smb.conf helps to project browse announcements
to remote network segments via unicast UDP. Similarly, the 
<command>remote browse sync</command> parameter of <filename>smb.conf</filename>
implements browse list collation using unicast UDP.
</para>

<para>
Secondly, in those networks where Samba is the only SMB server technology
wherever possible &nmbd; should be configured on one (1) machine as the WINS
server. This makes it easy to manage the browsing environment. If each network
segment is configured with it's own Samba WINS server, then the only way to
get cross segment browsing to work is by using the 
<command>remote announce</command> and the <command>remote browse sync</command>
parameters to your <filename>smb.conf</filename> file.
</para>

<para>
If only one WINS server is used for an entire multi-segment network then
the use of the <command>remote announce</command> and the 
<command>remote browse sync</command> parameters should NOT be necessary.
</para>

<para>
As of Samba 3 WINS replication is being worked on. The bulk of the code has
been committed, but it still needs maturation.
</para>

<para>
Right now samba WINS does not support MS-WINS replication. This means that
when setting up Samba as a WINS server there must only be one &nmbd; configured
as a WINS server on the network. Some sites have used multiple Samba WINS
servers for redundancy (one server per subnet) and then used 
<command>remote browse sync</command> and <command>remote announce</command>
to affect browse list collation across all
segments. Note that this means clients will only resolve local names,
and must be configured to use DNS to resolve names on other subnets in
order to resolve the IP addresses of the servers they can see on other
subnets. This setup is not recommended, but is mentioned as a practical
consideration (ie: an 'if all else fails' scenario).
</para>

<para>
Lastly, take note that browse lists are a collection of unreliable broadcast
messages that are repeated at intervals of not more than 15 minutes. This means
that it will take time to establish a browse list and it can take up to 45
minutes to stabilise, particularly across network segments.
</para>

</sect1>

<sect1>
<title>How browsing functions and how to deploy stable and 
dependable browsing using Samba</title>


<para>
As stated above, MS Windows machines register their NetBIOS names 
(i.e.: the machine name for each service type in operation) on start 
up. Also, as stated above, the exact method by which this name registration 
takes place is determined by whether or not the MS Windows client/server 
has been given a WINS server address, whether or not LMHOSTS lookup 
is enabled, or if DNS for NetBIOS name resolution is enabled, etc.
</para>

<para>
In the case where there is no WINS server all name registrations as 
well as name lookups are done by UDP broadcast. This isolates name 
resolution to the local subnet, unless LMHOSTS is used to list all 
names and IP addresses. In such situations Samba provides a means by 
which the samba server name may be forcibly injected into the browse 
list of a remote MS Windows network (using the 
<command>remote announce</command> parameter).
</para>

<para>
Where a WINS server is used, the MS Windows client will use UDP 
unicast to register with the WINS server. Such packets can be routed 
and thus WINS allows name resolution to function across routed networks.
</para>

<para>
During the startup process an election will take place to create a 
local master browser if one does not already exist. On each NetBIOS network 
one machine will be elected to function as the domain master browser. This 
domain browsing has nothing to do with MS security domain control. 
Instead, the domain master browser serves the role of contacting each local 
master browser (found by asking WINS or from LMHOSTS) and exchanging browse 
list contents. This way every master browser will eventually obtain a complete 
list of all machines that are on the network. Every 11-15 minutes an election 
is held to determine which machine will be the master browser. By the nature of 
the election criteria used, the machine with the highest uptime, or the 
most senior protocol version, or other criteria, will win the election 
as domain master browser.
</para>

<para>
Clients wishing to browse the network make use of this list, but also depend 
on the availability of correct name resolution to the respective IP 
address/addresses. 
</para>

<para>
Any configuration that breaks name resolution and/or browsing intrinsics 
will annoy users because they will have to put up with protracted 
inability to use the network services.
</para>

<para>
Samba supports a feature that allows forced synchonisation 
of browse lists across routed networks using the <command>remote 
browse sync</command> parameter in the <filename>smb.conf</filename> file. 
This causes Samba to contact the local master browser on a remote network and 
to request browse list synchronisation. This effectively bridges 
two networks that are separated by routers. The two remote 
networks may use either broadcast based name resolution or WINS 
based name resolution, but it should be noted that the <command>remote 
browse sync</command> parameter provides browse list synchronisation - and 
that is distinct from name to address resolution, in other 
words, for cross subnet browsing to function correctly it is 
essential that a name to address resolution mechanism be provided. 
This mechanism could be via DNS, <filename>/etc/hosts</filename>, 
and so on.
</para>

</sect1>

<sect1>
<title>Use of the <command>Remote Announce</command> parameter</title>
<para>
The <command>remote announce</command> parameter of 
<filename>smb.conf</filename> can be used to forcibly ensure
that all the NetBIOS names on a network get announced to a remote network.
The syntax of the <command>remote announce</command> parameter is:
<programlisting>
        remote announce = <replaceable>a.b.c.d [e.f.g.h]</replaceable> ...
</programlisting>
_or_
<programlisting>
        remote announce = <replaceable>a.b.c.d/WORKGROUP [e.f.g.h/WORKGROUP]</replaceable> ...
</programlisting>

where:
<variablelist>
<varlistentry><term><replaceable>a.b.c.d</replaceable> and 
<replaceable>e.f.g.h</replaceable></term>
<listitem><para>is either the LMB (Local Master Browser) IP address
or the broadcst address of the remote network.
ie: the LMB is at 192.168.1.10, or the address
could be given as 192.168.1.255 where the netmask
is assumed to be 24 bits (255.255.255.0).
When the remote announcement is made to the broadcast
address of the remote network every host will receive
our announcements. This is noisy and therefore
undesirable but may be necessary if we do NOT know
the IP address of the remote LMB.</para></listitem>
</varlistentry>

<varlistentry>
<term><replaceable>WORKGROUP</replaceable></term>
<listitem><para>is optional and can be either our own workgroup
or that of the remote network. If you use the
workgroup name of the remote network then our
NetBIOS machine names will end up looking like
they belong to that workgroup, this may cause
name resolution problems and should be avoided.
</para></listitem>
</varlistentry>
</variablelist>
</para>

</sect1>

<sect1>
<title>Use of the <command>Remote Browse Sync</command> parameter</title>

<para>
The <command>remote browse sync</command> parameter of 
<filename>smb.conf</filename> is used to announce to
another LMB that it must synchronise it's NetBIOS name list with our
Samba LMB. It works ONLY if the Samba server that has this option is
simultaneously the LMB on it's network segment.
</para>

<para>
The syntax of the <command>remote browse sync</command> parameter is:

<programlisting>
remote browse sync = <replaceable>a.b.c.d</replaceable>
</programlisting>

where <replaceable>a.b.c.d</replaceable> is either the IP address of the remote LMB or else is the network broadcast address of the remote segment.
</para>

</sect1>

<sect1>
<title>Use of WINS</title>

<para>
Use of WINS (either Samba WINS _or_ MS Windows NT Server WINS) is highly
recommended. Every NetBIOS machine registers it's name together with a
name_type value for each of of several types of service it has available.
eg: It registers it's name directly as a unique (the type 0x03) name.
It also registers it's name if it is running the lanmanager compatible
server service (used to make shares and printers available to other users)
by registering the server (the type 0x20) name.
</para>

<para>
All NetBIOS names are up to 15 characters in length. The name_type variable
is added to the end of the name - thus creating a 16 character name. Any
name that is shorter than 15 characters is padded with spaces to the 15th
character. ie: All NetBIOS names are 16 characters long (including the
name_type information).
</para>

<para>
WINS can store these 16 character names as they get registered. A client
that wants to log onto the network can ask the WINS server for a list
of all names that have registered the NetLogon service name_type. This saves
broadcast traffic and greatly expedites logon processing. Since broadcast
name resolution can not be used across network segments this type of
information can only be provided via WINS _or_ via statically configured
<filename>lmhosts</filename> files that must reside on all clients in the
absence of WINS.
</para>

<para>
WINS also serves the purpose of forcing browse list synchronisation by all
LMB's. LMB's must synchronise their browse list with the DMB (domain master
browser) and WINS helps the LMB to identify it's DMB. By definition this
will work only within a single workgroup. Note that the domain master browser
has NOTHING to do with what is referred to as an MS Windows NT Domain. The
later is a reference to a security environment while the DMB refers to the
master controller for browse list information only.
</para>

<para>
Use of WINS will work correctly only if EVERY client TCP/IP protocol stack
has been configured to use the WINS server/s. Any client that has not been
configured to use the WINS server will continue to use only broadcast based
name registration so that WINS may NEVER get to know about it. In any case,
machines that have not registered with a WINS server will fail name to address
lookup attempts by other clients and will therefore cause workstation access
errors.
</para>

<para>
To configure Samba as a WINS server just add 
<command>wins support = yes</command> to the <filename>smb.conf</filename>
file [globals] section.
</para>

<para>
To configure Samba to register with a WINS server just add
"wins server = a.b.c.d" to your smb.conf file [globals] section.
</para>

<important><para>
Never use both <command>wins support = yes</command> together
with <command>wins server = a.b.c.d</command>
particularly not using it's own IP address.
Specifying both will cause &nmbd; to refuse to start!
</para></important>

<sect2>
<title>WINS Replication</title>

<para>
Samba-3 permits WINS replication through the use of the <filename>wrepld</filename> utility.
This tool is not currently capable of being used as it is still in active development.
As soon as this tool becomes moderately functional we will prepare man pages and enhance this
section of the documentation to provide usage and technical details.
</para>

</sect2>
<sect2>
<title>Static WINS Entries</title>

<para>
New to Samba-3 is a tool called <filename>winsedit</filename> that may be used to add
static WINS entries to the WINS database. This tool can be used also to modify entries
existing in the WINS database.
</para>

<para>
The development of the winsedit tool was made necessary due to the migration
of the older style wins.dat file into a new tdb binary backend data store.
</para>

</sect2>
</sect1>

<sect1>
<title>Do NOT use more than one (1) protocol on MS Windows machines</title>

<para>
A very common cause of browsing problems results from installing more than
one protocol on an MS Windows machine.
</para>

<para>
Every NetBIOS machine takes part in a process of electing the LMB (and DMB)
every 15 minutes. A set of election criteria is used to determine the order
of precidence for winning this election process. A machine running Samba or
Windows NT will be biased so that the most suitable machine will predictably
win and thus retain it's role.
</para>

<para>
The election process is "fought out" so to speak over every NetBIOS network
interface. In the case of a Windows 9x machine that has both TCP/IP and IPX
installed and has NetBIOS enabled over both protocols the election will be
decided over both protocols. As often happens, if the Windows 9x machine is
the only one with both protocols then the LMB may be won on the NetBIOS
interface over the IPX protocol. Samba will then lose the LMB role as Windows
9x will insist it knows who the LMB is. Samba will then cease to function
as an LMB and thus browse list operation on all TCP/IP only machines will
fail.
</para>

<para><emphasis>
Windows 95, 98, 98se, Me are referred to generically as Windows 9x.
The Windows NT4, 2000, XP and 2003 use common protocols. These are roughly
referred to as the WinNT family, but it should be recognised that 2000 and
XP/2003 introduce new protocol extensions that cause them to behave 
differently from MS Windows NT4. Generally, where a server does NOT support
the newer or extended protocol, these will fall back to the NT4 protocols.
</emphasis></para>

<para>
The safest rule of all to follow it this - USE ONLY ONE PROTOCOL!
</para>

</sect1>

<sect1>
<title>Name Resolution Order</title>

<para>
Resolution of NetBIOS names to IP addresses can take place using a number
of methods. The only ones that can provide NetBIOS name_type information
are:</para>

<simplelist>
<member>WINS: the best tool!</member>
<member>LMHOSTS: is static and hard to maintain.</member>
<member>Broadcast: uses UDP and can not resolve names across remote segments.</member>
</simplelist>

<para>
Alternative means of name resolution includes:</para>
<simplelist>
<member>/etc/hosts: is static, hard to maintain, and lacks name_type info</member>
<member>DNS: is a good choice but lacks essential name_type info.</member>
</simplelist>

<para>
Many sites want to restrict DNS lookups and want to avoid broadcast name
resolution traffic. The "name resolve order" parameter is of great help here.
The syntax of the "name resolve order" parameter is:
<programlisting>
name resolve order = wins lmhosts bcast host
</programlisting>
_or_
<programlisting>
name resolve order = wins lmhosts       (eliminates bcast and host)
</programlisting>
The default is:
<programlisting>
name  resolve order = host lmhost wins bcast
</programlisting>.
where "host" refers the the native methods used by the Unix system
to implement the gethostbyname() function call. This is normally
controlled by <filename>/etc/host.conf</filename>, <filename>/etc/nsswitch.conf</filename> and <filename>/etc/resolv.conf</filename>.
</para>
</sect1>
</chapter>