d550a8380ddbdf5b247346a383df34a2b4c40214
[samba.git] / source3 / nameannounce.doc
1 this module deals with announcements: the sending of announcement requests
2 and the sending of announcements either to refresh other servers' records
3 or as a response to announcement requests.
4
5
6 /*************************************************************************
7   announce_master()
8   *************************************************************************/
9
10 this function is responsible for announcing samba as a master browser
11 to all known primary domain controllers.
12
13 this announcement is sent out at CHECK_TIME_MST_ANNOUNCE minute
14 intervals, only if samba is a master browser on one or more of
15 its local interfaces.
16
17 if no domain controller has been specified (lp_domain_controller())
18 samba goes through its list of servers looking for primary domain
19 controllers. when it finds one (other than itself) it will either
20 initiate a NAME_QUERY_PDC_SRV_CHK by broadcast or with a WINS
21 server. this will result in a NAME_STATUS_PDC_SRV_CHK, which
22 will result in a sync browse list and an announcement
23 ANN_MasterAnnounce being sent (see sync_server()).
24
25 if a domain controller has been specified, samba will search for
26 a primary domain controller for its workgroup (either by directed
27 packet or by broadcast if it cannot resolve the domain controller
28 name using DNS), which results in the same action as listed above.
29
30
31 /*************************************************************************
32   announce_host()
33   *************************************************************************/
34
35 this complex-looking function is responsible for announcing samba's
36 existence to other servers by broadcast. the actual announcement
37 is carried out by announce_server().
38
39 the time period between samba's announcement will stretch from one
40 minute to twelve minutes by one minute. if samba has received an
41 announce request from a master browser, then it should answer at
42 any random interval between zero and thirty seconds after the
43 request is received. this is to ensure that the master browser
44 does not get overloaded with responses!
45
46
47 /*************************************************************************
48   announce_server()
49   *************************************************************************/
50
51 this function is responsible for sending announcement packets.
52 these packets are received by other servers, which will then
53 update their records accordingly: what services we have, our
54 name, our comment field and our time to live (to name a few).
55
56 if we are a master browser, then using do_announce_host() we
57 must send an announcement notifying members of that workgroup
58 that we are their master browser, and another announcement
59 indicating to all backup browsers and master browsers that
60 we are a master browser.
61
62 (note: if another master browser receives this announcement
63 and thinks that it is also the master browser for this
64 workgroup, it stops being a master browser and forces an
65 election).
66
67 if we are not a master browser, then we send an announcement
68 notifying the master browser that we are a member of its
69 workgroup.
70
71
72 /*************************************************************************
73   remove_my_servers()
74   *************************************************************************/
75
76 this function is responsible for informing other servers that
77 samba is about to go down. it announces, on all subnets, that
78 samba's time to live is zero and that it has no services.
79
80
81 /*************************************************************************
82   do_announce_host()
83   *************************************************************************/
84
85 this function is responsible for sending out an announcement
86 MAILSLOT browse packet. it contains information such as the
87 time to live, name of the server, services that the server
88 offers etc.
89
90 the format of this MAILSLOT browse packet is described in
91 draft-heizer-cifs-v1-spec-00.txt 3.9.50.4.1 page 165-6.
92
93
94 /*************************************************************************
95   announce_backup()
96   *************************************************************************/
97
98 this function is responsible for getting master browsers and domain
99 controllers to send us lists of backup servers. this is done by
100 sending an ANN_GetBackupListReq browse mailslot.
101
102 the master browser, or primary domain controller, should respond 
103 with an ANN_GetBackupListResp browse mailslot containing the list
104 of backup servers.
105
106
107 /*************************************************************************
108   sync_server()
109   *************************************************************************/
110
111 this function is responsible for initiating a sync browse list
112 sequence and, if necessary, carrying out an ANN_MasterAnnouncement
113 to the primary domain controller (that we are also sync'ing
114 browse lists with).
115
116 see nameservresp.c:response_name_status_check().
117
118
119 /*************************************************************************
120   announce_request()
121   *************************************************************************/
122
123 this function is responsible for sending an announcement request to
124 another server. this server should respond with an announcement.
125
126 if the announce request is sent to WORKGROUP(0x1e) then members of
127 the workgroup will respond (with ANN_HostAnnounce packets)
128
129 if the announce request is sent to WORKGROUP(0x1d) then the master
130 browser of the workgroup should respond (ANN_LocalMasterAnnounce).
131 this is untested.
132
133 if the announce request is sent to ^1^2__MSBROWSE__^2(0x1) then
134 (and this is pure speculation), all backup browsers and master
135 browsers should respond with ANN_DomainAnnounce packets.
136 this is untested.
137