docs/devel/wins.xml

   1 <?xml version="1.0" encoding="iso-8859-1"?>
   2 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
   3                 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
   4   <!ENTITY % global_entities SYSTEM '../entities/global.entities'>
   5   %global_entities;
   6 ]>
   7 <chapter id="wins">
   8 <chapterinfo>
   9         <author>
  10                 <firstname>Gerald</firstname><surname>Carter</surname>
  11         </author>
  12         <pubdate>October 2002</pubdate>
  13 </chapterinfo>
  14
  15
  16 <title>Samba WINS Internals</title>
  17
  18
  19 <sect1>
  20 <title>WINS Failover</title>
  21
  22
  23 <para>
  24 The current Samba codebase possesses the capability to use groups of WINS
  25 servers that share a common namespace for NetBIOS name registration and
  26 resolution.  The formal parameter syntax is
  27 </para>
  28
  29 <para><programlisting>
  30         WINS_SERVER_PARAM       = SERVER [ SEPARATOR SERVER_LIST ]
  31         WINS_SERVER_PARAM       = &quot;wins server&quot;
  32         SERVER                  = ADDR[:TAG]
  33         ADDR                    = ip_addr | fqdn
  34         TAG                     = string
  35         SEPARATOR               = comma | \s+
  36         SERVER_LIST             = SERVER [ SEPARATOR SERVER_LIST ]
  37 </programlisting></para>
  38
  39 <para>
  40 A simple example of a valid wins server setting is
  41 </para>
  42
  43 <para><programlisting>
  44 [global]
  45         wins server = 192.168.1.2 192.168.1.3
  46 </programlisting></para>
  47
  48 <para>
  49 In the event that no TAG is defined in for a SERVER in the list, smbd assigns a default
  50 TAG of &quot;*&quot;.  A TAG is used to group servers of a shared NetBIOS namespace together.  Upon
  51 startup, nmbd will attempt to register the netbios name value with one server in each
  52 tagged group.
  53 </para>
  54
  55 <para>
  56 An example using tags to group WINS servers together is show here.  Note that the use of
  57 interface names in the tags is only by convention and is not a technical requirement.
  58 </para>
  59
  60
  61 <para><programlisting>
  62 [global]
  63         wins server = 192.168.1.2:eth0 192.168.1.3:eth0 192.168.2.2:eth1
  64 </programlisting></para>
  65
  66 <para>
  67 Using this configuration, nmbd would attempt to register the server's NetBIOS name
  68 with one WINS server in each group.  Because the &quot;eth0&quot; group has two servers, the
  69 second server would only be used when a registration (or resolution) request to
  70 the first server in that group timed out.
  71 </para>
  72
  73 <para>
  74 NetBIOS name resolution follows a similar pattern as name registration.  When resolving
  75 a NetBIOS name via WINS, smbd and other Samba programs will attempt to query a single WINS
  76 server in a tagged group until either a positive response is obtained at least once or
  77 until a server from every tagged group has responded negatively to the name query request.
  78 If a timeout occurs when querying a specific WINS server, that server is marked as down to
  79 prevent further timeouts and the next server in the WINS group is contacted.  Once marked as
  80 dead, Samba will not attempt to contact that server for name registration/resolution queries
  81 for a period of 10 minutes.
  82 </para>
  83
  84 </sect1>
  85 </chapter>