untermud/DOC/
untermud/DOC/U/
untermud/DOC/U/U-examples/
untermud/DOC/internals/
untermud/DOC/wizard/
untermud/MISC/
untermud/MISC/dbchk/
untermud/RWHO/
untermud/RWHO/rwhod/
From AMOLITOR@EAGLE.WESLEYAN.EDU Sun Jun  9 19:15:33 1991
Received: by hussar.dco.dec.com (5.57/ULTRIX-fma-111690);
	id AA05083; Sun, 9 Jun 91 19:15:31 -0400
Received: from eagle.wesleyan.edu by decuac.DEC.COM (5.61/Ultrix-fma)
	id AA09244; Sun, 9 Jun 91 19:15:16 -0400 XXX
Message-Id: <9106092315.AA09244@decuac.DEC.COM>
Date: 9-JUN-1991 19:14:13.73
From: Andrew <AMOLITOR@EAGLE.WESLEYAN.EDU>
Subject: RWHO dox..
To: mjr@decuac.DEC.COM, jennifer@hardy.math.okstate.edu
Status: R

	First cut. As usual, written in my fabulously clear and wonderful
style. Check for stupid errors? Re-write? Distribute? I dunno...


	A


--------
mwhod - the RWHO server
=======================


Invoking the RWHO server
------------------------

	The RWHO server accepts following command line arguments:

-S <port number>

	sets the TCP port to which WHO information requests should be
directed (i.e. the port users connect to to see who's on where). This
defaults to 6889.

-P <port number>

	sets the UDP port to on which the server listens for informational
datagrams from MUDs and peer RWHO servers. This defaults to 6888.

-f <file name>

	loads a file of MUD definitions into the server's tables. See below for
more details on the format of this file.

-n <server name>

	sets the server name. This must be set if we wish the propagate our
data to peer servers, and does not default to anything.

-c <number>

	sets the number of seconds between passes over the internal tables to
expire old entries. This defaults to 120 seconds.

-p <number>

	sets the number of seconds between passes over the internal tables to
propagate entries to out peer servers. This defaults to 120 seconds.

-d
	turns on debugging output. Debugging output is directed at standard
output.

-l
	turns on logging. Logged data is directed at standard output.

-D
	makes the RWHO server turn itself into a daemon, if this option is
compiled in (with #define DAEMON, or the equivalent). If SETSID is defined at
compile time, the server will also disassociate from its controlling tty
with a setsid() call. This is a Posix-ism, and your machine may not support it.


Configuring the RWHO server
---------------------------

	The lines of the data file loaded with the -f flag look like this:

OP hostname portnumber name password comments

	where OP is a word made up from the letters C, P, W, and may be
followed (without space) by a single digit generation number. If no
generation number is specified, the entry has generation number 0. Each line
defines a mud entry in the internal tables -- in particular, peer RWHO servers
are a special case of a mud entry. The semantics are as follows:

C
	defines a simple mud entry, one from which we will accept data about
who has logged on and off, if the mud is up or down, etc.

P
	defines a peer RWHO server. We periodically (with the interval set
with -p on the command line) forward to each peer all our data about
muds with generation numbners strictly smaller than the generation number of
the peer. The portnumber is meaningful only for peers, and should be the number
of the datagram port that peer expects information on (as set with -P).

W
	specifies that the mud entry has wizard status, and can define new mud
entries in our tables (by sending a suitable datagram). Only a mud entry so
tagged can send W-type datagrams (see below, and see also mwhocmd
documentation)
	
RWHO Datagram Format
--------------------

	Datagrams are formatted as a sequence of arguments, separated by tab
characters. All requests have the form:

OP<tab>Mudname<tab>Mudpassword[optional tab separated args]

	The mud name and password are chacked against internal tables (as
defined in the file loaded with the -f flag on the command line, typically),
and the datagram is discarded if these are not valid.

	Any valid datagram from a remote MUD (or peer server) causes the
that entity's time-to-live field in internal tables to be updated. Thus,
remotes should send some sort of packet every 120 seconds (or other interval
as specified with the -c flag) in order to remain listed as 'alive' by this
RWHO server.

	Supported OPs are (spaces below should be tabs, of course):

U name password mudname muduptime generation comments

	lets the server know that the named mud has rebooted. This clears the
list of users accosicated with that mud.

M name password mudname muduptime generation comments

	defines or updates a mud entry (for WHO list purposes -- this is
different from the W op below). This can be used by a mud to ping a server,
withough clearing the list of users (otherwise this is identical to U).

D name password

	tells the server that the named mud is down (sent when a mud shuts
down gracefully, typically).

A name password mudname userid login-time generation [user-name]

	adds a new user to the list of who's logged on to the named mud.

Z name password mudname userid

	deletes a user from the list of who's logged on to the specified mud.

W name password mudentrystring

	a remote mud (or peer) that is set WIZARD in our internal tables can
define a new remote mud entry (a la the file of mud definitions loaded with
-f on the command line) based on ARGS.



mwhocmd - The RWHO control client
=================================

	mwhod does NOT send wizard packets to peer servers -- there's no scope
for it. However, included in the RWHO distribution is a pseudo-mud, mwhocmd,
that will send a datagram to an RWHO server. This will send a single packet to
a specified host on port 6888 (currently this is hardcoded). It works like
this:

mwhocmd -s <host> -c '<command>'

	the command is sent absolutely as is, and so must be tab formatted
etc, as indicated above.

	One could, then, have a mud entry in the file one initially loads when
invoking mwhod:

CW 127.0.0.1 0000 CONTROL CONTROLPWD This is the controller Mud

	and then senmd your mwhod data from a shell prompt with:

mwhod -s <rwhod host> -c'<text>'

	where <text> is:

A<tab>CONTROL<tab>CONTROLPWD<tab>FrobMUD<tab>bob<tab>17686<tab>2

	to say that a user logged on to FrobMUD at time 17686 seconds after
Jan 1 1970, and that this is a 2nd generation packet (i.e. has been forwarded
twice).

	or:

W<tab>CONTROL<tab>CONTROLPWD<tab>C host.site.dom 000 GronkMUD gronk comment


	to say that there is an ordniary MUD from which we should accept user
data at 'host.site.dom', the mud is named 'GronkMUD', will be using the password
'gronk', and the comment attached to this MUD is simply the text 'comment'.
Note that there are NO tabs in after the 'C', to prevent mwhod from hacking up
the MUD definition when it receives the packet.