/usr/share/GNUstep/Documentation/Developer/Tools/Reference/gdomap.html is in gnustep-base-doc 1.24.7-1build2.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 | <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<title>gdomap documentation</title>
</head>
<body>
<font face="serif">
<a href="BaseTools.html">Up</a>
<br />
<h1><a name="title$gdomap">gdomap documentation</a></h1>
<h3>Authors</h3>
<dl>
<dt>Richard Frith-Macdonald (<a href="mailto:richard@brainstorm.co.uk"><code>richard@brainstorm.co.uk</code></a>)</dt>
<dd>
</dd>
</dl>
<p><b>Copyright:</b> (C) 1998 Free Software Foundation, Inc.</p>
<div>
<hr width="50%" align="left" />
<h3>Contents -</h3>
<ol>
<li>
<a href="#001000000000">gdomap</a>
</li>
<li>
<a href="#001001000000">Usage Scenario</a>
</li>
<li>
<a href="#001002000000">How it Works and Why</a>
</li>
<li>
<a href="#001003000000">Communications Protocol</a>
</li>
<li>
<a href="#001004000000">Notes for Packagers</a>
</li>
</ol>
<hr width="50%" align="left" />
</div>
<h1><a name="001000000000">gdomap</a></h1>
<p>
The gdomap daemon is used by GNUstep programs to look up distributed
objects of processes running across the network (and between different
user accounts on a single machine). The deamon is <em>NOT</em> used
for lookup where two processes belonging to the same user are using a
host-local connection.
</p>
<p>
If you are packaging GNUstep for inclusion in a software distribution
you may want to skip to the final section of this document.
</p>
<p>
Usually the gdomap daemon is started at system boot time and binds
itself to port 538. (See the GNUstep Build Guide for a sample
startup script.) It expects to receive fixed-size request packets
for registering, deregistering, and looking up distributed objects
servers. The response packets vary in length depending on the type
and content of the information requested. In addition, limited
support for federation is provided by a rudimentary gdomap-gdomap
communications protocol.
</p>
<p>
What follows is a description of gdomap from a developer
perspective. For information pertinent for users, such as how to
configure and start up gdomap, please see the man page for more
information ("man 8 gdomap").
</p>
<p>
The name server is intended to work with both the UDP and the TCP
protocols. It is intended that the TCP interface be used by
GNUstep programs, while the UDP interface is intended primarily
for communication between name servers on different machines.
</p>
<h2><a name="001001000000">Usage Scenario</a></h2>
<p>
A complete distributed-objects "conversation" between a client
and a server looks like the outline below. The gdomap daemon
only plays a role in the "pre-" and "post-" phases. Everything
else is conducted "peer-to-peer" between the two GNUstep
processes.
</p>
<dl>
<dt>Pre-conversation</dt>
<dd>
<ol>
<li>
Server registers an object as being available as the
'root object' on a particular port with a specific
name.
</li>
<li>
Client looks up a port by name.
</li>
</ol>
</dd>
<dt>Conversation</dt>
<dd>
<ol>
<li>
Client connects to the port and asks for the root
object.
</li>
<li>
Server returns proxy to root object.
</li>
<li>
Client then proceeds to send messages to the object.
</li>
<li>
Server sends message responses except where methods
are declared 'oneway'.
</li>
<li>
The server may also send messages to the client and
have the client send responses.
</li>
<li>
Eventually, the client or the server disconnects by
invalidating port or connection or just exiting.
</li>
</ol>
</dd>
<dt>Post-conversation</dt>
<dd>
On shutdown, the server unregisters the service name and
port it used.
</dd>
</dl>
<h2><a name="001002000000">How it Works and Why</a></h2>
<p>
The fixed size of a request packet was chosen for maximum
ease and speed of implementation of a non-blocking name server.
The server knows how much it needs to read and can therefore
usually do a read as a single operation since it doesn't have
to read a little, figure out request length, allocate a buffer,
and read the rest.
</p>
<p>
The server name length (bytes) is specified - no assumptions
should be made about whether the name contains nul characters
or indeed about the name at all. This is future-proofing.
</p>
<p>
Why UDP as well as TCP?
The OpenStep specification says that a connection may be
established to any host on the local network which supplys a
named service if the host name is specified as '*'.
</p>
<p>
This means that the application must poll to see if it can
find a server with the name it wants. The polling could take
a huge amount of time!
</p>
<p>
To make this all easier - the server is capable of supplying
a list of those hosts on the local network which it knows to
have (or have had) a name server running on them.
</p>
<p>
The application then need only poll those name servers to find
the service it wants.
</p>
<p>
However - to give the application a list of hosts, the name
server must have got the information from somewhere.
To gather the information the server has to poll the machines
on the net which would take ages using TCP since attempts to
talk to machines which are down or do not exist will take a
while to time out.
</p>
<p>
To make things speedy, the server sends out GDO_PROBE requests
on UDP to all the machines on the net when it starts up.
Each machine which has a name server notes that the new name
server has started up and sends back a GDOPREPLY packet so
that the new name server will know about it.
</p>
<p>
Things are never perfect though - if a name server dies, the
other name servers won't know, and will continue to tell
applications that it is there.
</p>
<p>
Port type codes - these are used to say what the port is for so
that clients can look up only the names that are relevant to them.
This is to permit the name server to be used for multiple
communications protocols (at the moment, tcp or udp) and for
different systems (distributed objects or others).
This guarantees that if one app is using DO over UDP, its services
will not be found by an app which is using DO over TCP.
</p>
<h2><a name="001003000000">Communications Protocol</a></h2>
<p>
The communications protocol is identical for both TCP and UDP
and consists of a simple request-response sequence.
</p>
<p>
Each request is a single message consisting of -
</p>
<ol>
<li>
a single byte request type
</li>
<li>
a single byte giving name length,
</li>
<li>
a single byte specifying the type of port being registered
or looked up, or a nul byte for probe operations.
</li>
<li>
a single nul byte.
</li>
<li>
a four byte port number in network byte order must be
present for register operations, otherwise this is zero.
</li>
<li>
a service name of 0 to GDO_NAME_MAX_LEN bytes (or two IP
addresses in network byte order and an optional list of
additional addresses for probe operations)
</li>
<li>
0 to GDO_NAME_MAX_LEN nul bytes padding the service name to
its full size.
</li>
<li>
a terminating nul byte.
</li>
</ol>
<p>
The total is always sent in a packet with everything after the
service name (except the final byte) cleared to nul bytes.
</p>
<p>
Each response consists of at least 4 bytes and depends on the
corresponding Request Type and where it came from as follows -
</p>
<dl>
<dt>GDO_LOOKUP</dt>
<dd>
Looks up the server name and returns its port number.
Response is the port number in network byte order, or zero
if the named server was not registered.
</dd>
<dt>GDO_REGISTER</dt>
<dd>
Registers the given server name with a port number. This
service is only available to processes on the same host as
the name server. Response is the port number in network
byte order, or zero if the named server was already
registered.
</dd>
<dt>GDO_UNREG</dt>
<dd>
Un-register the server name and return old port number. If
the server name is of length zero, and the port is non-zero
then all names for the port are unregistered. This service
is only available to a process on the same host as this name
server. Response is the old port number in network byte
order, or zero if the name could not be un-registered. If
multiple names were unregistered the response is the port
for those names.
</dd>
<dt>GDO_SERVERS</dt>
<dd>
Return a list of the known servers on the local net.
Response is an unsigned long (in network byte order) saying
how many servers the name server knows about, followed by a
list of their IP addresses in network byte order. NB. This
response may not be possible over UDP as the response length
may exceed the maximum UDP packet size.
</dd>
<dt>GDO_NAMES</dt>
<dd>
Return a list of registered names known to the server.
Response is an unsigned long (in network byte order) saying
how many bytes of data are to follow, followed by a list of
the names each preceeded by the name length (a single byte)
and port type (a byte). NB. This response may not be
possible over UDP as the response length may exceed the
maximum UDP packet size.
</dd>
</dl>
<p>
The following are used for communications between name servers -
</p>
<dl>
<dt>GDO_PROBE</dt>
<dd>
Requests a response Passes two IP addresses in the name
field - first the address of the sender, next that of the
recipient. The packet may (optionally) include a variable
number of addresses (as specified by the name length minus
the size of the two addresses), each of which is an internet
address on which the sender is also listening. For a
request from a name server via UDP there is no response, but
a GDO_REPLY request is sent. For a request from a
non-name-server, or a TCP connect, the response is the port
number of this server in network byte order.
</dd>
<dt>GDO_PREPLY</dt>
<dd>
Replies to a GDO_PROBE via UDP from a name server. The
format of the message is as for GDO_PROBE. No response is
sent.
</dd>
</dl>
<h2><a name="001004000000">Notes for Packagers</a></h2>
<p>
The gdomap process is a system daemon used to coordinate
services between different machines. As such it should be
started (as root) at system boot time (if inter-host messaging
is desired), and you need to write the appropriate startup
scripts for your system and put them in place when the
package is installed.<br />
Alternatively you may install gdomap setuid to run as root,
and GNUstep programs will launch it on demand ... but this
is not recommended as it provides lass control than when
you write a proper startup script.
</p>
<p>
The default operation of gdomap is to probe the hosts on the
local network to find other machines with copies of gdomap
running, so that all the machines on the network can be kept
informed of the seervices provided by GNUstep servers.<br />
This probing may be considered unfriendly by other users of
the LAN, so it is usually better to provide a configuration
file specifying the IP addresses of machines to be probed,
and start up gdomap at boot time with the command line option
to tell it to read the file.
</p>
<br />
<a href="BaseTools.html">Up</a>
</font>
</body>
</html>
|